Help Files and Technical Documentation

I recently released version 2.4 of Complete Time Tracking. It was a fairly major release (despite the .1 version number increment) as with the update, which contains more than 30 enhancements, I released a new Professional edition for multi-user time tracking (the previous incarnation is now known as the Standard edition).

In light of this I am about to release a new web site for CTT which is a big improvement over the current site, containing more information, better layout, clear feature differences between the Standard and Professional editions, streamlined download and purchasing and so on.

Both of these efforts required a great deal of technical documentation. I do not claim to be an expert in technical documentation but here is my 30 second view and a few tips.

General copy (text) discussing product features should be written with the style "what not how". For example, you might write "Security access to more than forty features can be configured for each user" instead of "You can configure security access to more than forty features by selecting the user configuration option".

Conversely tutorials and instructional copy should be written with the style "how not what".

Web sites promoting your products should typically be written using "what not how", though it is often worthwhile to use "how not what" on FAQ pages and in online feature tours and video demonstrations.

Help files and user manuals usually contain a combination of the two styles. Users want to know both what is possible and how to do it.

A quite useful book for writing technical documentation is Microsoft Manual of Style for Technical Publications, which outlines which/what word forms to use, such as which vs. what, login vs. log in, can vs. may, when to use capitalization, guidelines for writing headings and subheadings and much more.

For help file creation I can highly recommend Help and Manual. Version 4 was recently released and contains some great new features. From the one help file project you can generate professional looking help files, PDF or MS Word user manuals, browser based help and more.

In all cases try to get someone else to review your copy. What sounds ok or is understandable to you might not be the case for other people. Take the following case as an example.

A user of Complete Time Tracking recently queried how to create categories. It is described in the online help but in my "how not what" email reply I said "Select the Configure Categories button on the toolbar...". The user replied "What is a toolbar? I only see some buttons along the top but nothing saying Configure Categories." The button icon and tooltip hint might not be as intuitive as I first thought. Perhaps I should have described how to perform the steps using the menu instead.

Programming Languages and Popularity

The following information provides a glimpse of the popularity of various programming languages, though not strictly from a shareware development point of view.

Tiobe Software maintains an interesting Programming Community Index. This index "gives an indication of the popularity of programming languages" using results from search engines when searching for web pages about the programming languages.

The September 2005 results show the top ten most popular programming languages to be:

1. Java (22.4%)
2. C (19.2%)
3. C++ (11.2%)
4. Perl (9.3%)
5. PHP (8.9%)
6. Visual Basic (6.5%, not including VB.NET)
7. C# (3.3%)
8. Python (3.0%)
9. JavaScript (1.8%)
10. Delphi/Kylix (1.7%)

VB.NET came in at number 15 with 0.7%. It should be noted that the rankings in the index likely bias languages that have been around for some time such as C and C++ over newer languages such as C# and Python. The (ratings) column in the index shows the trend over the last 12 months.

For comparison I performed a series of searches at jobs.com and computerjobs.com to gain an insight into what skills are currently being sought by organizations and hopefully generate more of a "current" popularity than the index above. I also included VB.NET. The most sought after programming languages in jobs with relative (comparable but not absolute) job numbers is shown in the following list:

1. Java (1284)
2. C++ (438)
3. C# (213)
4. VB (119)
5. VB.NET (90)
6. PHP (55)
7. C (51)
8. Perl (43)
9. Delphi/Kylix (18)
10. JavaScript (7)
11. Python (2)

This is largely what I would have expected.

A poll at GameDev.net asked "What language do you prefer to use for games?" The top six results from 994 votes were:

1. C++ (76.6%)
2. C (6.33%)
3. C# (4.12%)
4. Java (3.62%)
5. Python (2.21%)
6. Visual Basic (1.6%)

In October 2004 ProgrammersHeaven.com asked "What is your favorite programming language?" Of 1206 votes the top ten results were:

1. C++ (24%)
2. Visual Basic (14%)
3. C (13%)
4. Java (10%)
5. Assembly (6%)
6. Delphi (6%)
7. Visual Basic.NET (6%)
8. C# (4%)
9. Basic (3%)
10. Pascal (3%)

So which programming language should you use for your next shareware application? That's entirely up to you, though it will largely be determined by:

• What language(s) you have experience with.
• What kind of application (for example general desktop, web service, game, database) you are developing.
• The information and community support available for the language.
• Current trends.
• Any specific frameworks or libraries that you need to use.
• What operating system you are targetting.
• Whether you need to provide a plug-in or other interface to your application.
• The extent of distribution of the .NET framework redistributable (runtime).

Though some shareware developers are willing to switch languages for a new product and some are changing all future applications to be written in languages such as C# and VB.NET, most stick with a language that they already know.

Getting Started

It can be difficult to get started as a shareware developer. A large proportion of shareware developers are one-person operations. The ASP September 2004 Demographic Survey reports that 65% of the 353 members who participated run their shareware business themselves. A further 26% of shareware businesses were reported to be run by 2-4 people.

Being largely self-taught, shareware developers need to conduct a lot of initial research. In addition to writing code, which most shareware developers already have some experience with, shareware developers need to learn about web hosting and development, creating installation programs, writing help files, graphical design, writing license agreements, marketing, product pricing, how to provide effective customer support, software licensing and protection, software submission and distribution, advertising, search engine optimization, and payment and order processing.

Some of the work involved in establishing and growing a shareware business can obviously be outsourced. Graphical design, web development, marketing and search engine optimization are commonly performed by hired guns, but in the early days many shareware developers tend to take on these roles themselves.

Other than a few core things that you must learn before developing and releasing your first shareware application I believe that it is relatively simple to start a shareware business. Strive to learn as much as you can and over time you will acquire invaluable knowledge and skills that enable you to streamline your processes and improve your products.

Over time I will be covering a lot of the above knowledge areas and hope to provide some interesting details and my views on shareware development for new and experienced shareware developers.