Skip to main content

Learn How to Write Good Documentation for your Software

The ideal software would be free of errors and so easy to use that everybody would be familiar with it the minute they start the application. However, this is not the case in real life.

Besides the quality of the software product, there’s something else that makes or breaks the deal: technical support. The better the support software publishers and shareware authors provide, the more users are likely to buy the product.

Technical support for software products can be provided in several ways:

  • online product documentation
  • e-mail assistance
  • access to support forums maintained by software publishers
  • knowledge bases.

Good documentation may exclude in many cases the need for further forms of technical support. It is, however, not easy to write. One of the reasons why this happens is that it is difficult for shareware authors or other software developers to put themselves into the users’ shoes, since they are already thoroughly familiar with the application.

Read Me file

The first thing every software product should have is a text format "Read Me" file that includes the following:

  • Product Name and Version
  • Company and Author Name
  • Release date
  • Description (like "photo organizer")
  • A changelog (this should be a list of fixes and new features)
  • System requirements (CPU, RAM, disk space, operating systems supported)
  • Price, payment options and instructions
  • Copyright and distribution information (rules for people who want to distribute your product)
  • Contact details (email, phone, fax website and postal address)

The "Read Me" file is important because everybody who might be interested in your product is expecting it, including reviewers, users, or people who want to put your product on a CD for distribution with a magazine or on their website. The idea here is to minimize frustration associated with the information being too difficult to find, therefore you should put all in one place.

The Manual

The other thing shareware authors and software publishers need to provide with their product is the manual. The first thing you should think about when starting to write it is how your users are going to use it. Few are those that will bother reading it all before attempting to use your product. They are more likely to turn to it later, when they try to do something and cannot figure out how to do it, or when they find something they do not understand.

To help them, it is best to organize your documentation by tasks. "How to…" sections are more useful than merely documenting every command in order. Explanations are easier to understand if they are backed by pictures and diagrams, wherever possible. There should also be a chapter labeled "Troubleshooting", which provides answers to the most common problems. At first you will have to guess where those problems may occur, but a couple of upgrades to your product later, the feedback from the people who tried the product will tell you what the most common problems are.

The manual should be broken down into chapters, the first one telling what the other chapters contain, so that people could readily find what they need.

The interface

Another point worth mentionning is the interface. User friendly is not enough, the interface needs to be easy to use even if the user does not have an overall systems understanding, so screens need to be self-describing.

Online help or online documentation


There is also online help, or online documentation. The documentation put on the website for users to read has to show up in search results. It has to be organized in such a way that users, who are sure to be asking questions like "How can I…" or "Why can't I…" can find the answers quickly. Lots of examples showing how to do various tasks with the software product are also needed. A good idea is to include links to a glossary of terms that might be more difficult to understand.

* * * * * * * * * * * * * * * * * * * * *


Always bear in mind that anyone who has had a bad experience with a product tends to remember it for a long time and software is no different. That is why you should strive to make using your product as smooth an experience as possible, something proper support and documentation can help you achieve.

See also Writing Good Software Documentation.

Comments

Popular posts from this blog

The sign-in method you're trying to use isn't allowed. For more info, contact your network administrator

Above problem occur when you have not added a group (of which User try to login)  in your local policy login. To resolve the issue, follow the steps,
Log in as the administrator on the server, then start the Group Policy Management Editor by running the  gpmc.msc command from PowerShell or the Command Line window. 1. In the Group Policy Management window on the left hand side, select Group Policy Management. 2. Click to expand the  Forest tree node.
3. Click Domains.
4. Select your domain name.
5. Click Group Policy Objects. 6. In the right-hand window, double-click Default Domain Controllers Policy.
7. Right-click Default Domain Controllers Policy and Select Edit.
8. In the Group Policy Management Editor window, click Default Domain Controllers Policy.
9. Click Computer Configuration, and then click Policies.
10. Click Windows Settings, and then click Security Settings. 11. Click Local Policies and then click User Rights Assignments.
12. In the right pane, click Allow log on locally. 12. Cli…

ORA-38104: Columns referenced in the ON Clause cannot be updated

In my case, this error pertains to Oracle Merge query. After 30 minutes of time wastage and a lot of hunting on different forums, I come to know that where and why was my merge query throwing exception.

I was giving multiple criteria in ON clause of merge query, and was also trying to update a column which I have mentioned in ON clause. Once I remove that column from update clause of merge query, it executed successfully.

I hope that this will also works for you.

In case if this post help you, then please comment on it.

Thanks.

Cannot use the special principal 'sa'. (Microsoft SQL Server, Error: 15405)

Yesterday, I start SQL Server 2005 and try to connect with sa user but was enable to connect with the 'sa' user and got this error:

Cannot use the special principal 'sa' (Microsoft SQL Server, Error: 15405)After doing some google, I found out the solution which I am sharing so that others can get all the possible solutions from this article.
The titled message mean that your sa user is disabled. To enable it, you have to follow below mentioned steps:1) you have to change the authentication mode: go to Management Studio and open Object Explorer. Connect to your server and right-click on the server name, then select Properties. Go to Security tab and under Server Authentication select "SQL Server and Windows Authentication Mode".2) Also, after you follow the directions above, you will also need to explicitly enable the sa account as well. Go to Security->Logins. Right-click on the "sa" account, select "Properties". In the list on the lef…