Skip to main content

Writing Good Software Documentation

Writing software documentation may seem extremely easy for some of us, whereas others may consider it one of the most difficult tasks they could ever be asked to do.

The generic term for this kind of writing is "technical writing". A person who does this job is generally referred to as a "technical writer", with quite extensive knowledge of software and technology and with a deeper understanding of the logic behind the software, or a "technical writer", a person who, although somewhat overwhelmed by all the denominations and the algorithms of the software, is accurate in producing a proper technical text.

Nevertheless, regardless of the orientation of the writers, be them more technical than writers, there are some things that need to be considered before, during and after the writing process.

Before Writing

· Know the Software

  • Training
    Make sure you receive proper training for the software that you are about to document and that you have the software explained to you, step by step.
  • Experiment
    Have the software installed on your machine; make sure you also have access to as musch as possible of the necessary software related information, and that you have access to all the functionalities of the software. Explore all its functions, and don't be afraid to ask the engineers whenever you are not certain about the influence of, let's say, an unchecked checkbox or radio button on the process thatyou are documenting. Don't assume anything, you could be wrong.
  • Gather information
    This may mean older documents, definition documents for certain functionalities or specifications, general PowerPoint presentations, marketing documents, etc. They may help you along the way.

· Identify the Target Audience

This is of utmost importance. You have to know beforehand what kind of public the document you are about to produce addresses to, so that you know how to adjust and adapt the style and the informational content of the document. Again, ask the engineers, the product managers, about the audience. You don't want to be too technical for a non-technical audience, or vice versa.

· Keep It Simple

  • Avoid creating a lot of styles. Too many styles can make a document hard to follow.
  • Do not include header and footer in the first two pages of the document (the ones containing the name of the company that produces the application, the name of the document, date of creation, copyright issues, support department contact information, and document version history). Start using header and footer from the Table of Contents section.
  • Refrain from inserting symbols (such as exploding bombs or the like) for error messages or notes.
  • Use only black for text. You can highlight terms or names of buttons, menus, windows, tables, etc. by using bold letters or italics.

· Be Accurate

With Text

  • Respect all the documentation requests, coming either from the client or from your direct supervisor, pertaining to the contents and layout of the document.
  • Always check the spelling and grammar
  • Avoid ambiguous or empty phrases. Do not describe a checkbox by simply saying "Select here to do this." Explain the effect of checking or not that respective checkbox on the process that you are documenting and on the behavior of the software as a whole. Avoid describing fields by using a simple, for example, "Enter the file name", or "Enter user ID / password". You must provide more information, such as the location where files can be found or saved, the length and composition of user IDs and passwords, in what way the details provided by you in these fields will influence the evolution of the process you are documenting and the behavior of the entire software, etc.
  • Describe with accuracy text fields, checkboxes, radio buttons, spin boxes, drop-down lists, etc. Do not assume that the readers will know what they are or what they should contain.
  • Make sure that the names of user manuals or products that you refer to in your document are correct.
  • Use a simple NOTE whenever some particular aspect needs to be brought to the reader's attention.
  • Do not insult your reader's intelligence by pointing out the really obvious. For example, it suffices to state only once how to start the application. Any further reference to this inside the manual is not necessary.
  • Don't burden your readers with unnecessary, irrelevant information. What you need to do is fulfill your readers' need for information on a particular topic, not boast about your vast knowledge.
  • It is also preferable to express an idea in a simple way than risk an intricate, complex formulation.
  • Always be careful with gender-neutral writing. Prefer using the imperative mood (Do this..), the second person pronoun (you) over the third person plural pronoun "they" as singular pronoun (mainly because many of your readers may not grasp its real meaning) or over the third person singular pronoun "he" (you may sound gender-biased) or "the user". Also, avoid such phrases as "he/she" or "he or she".
  • When you have tables in your document, make sure you select from Table Properties the "Allow row to break across pages" option and, for the top row of your table, the "Repeat as header row at the top of each page" option. This way you will avoid those huge blank spaces created when a table is too big to fit in a smaller part of the page and it is automatically moved on the next page of the document.

With Pictures / Screen Shots / Diagrams

  • Prefer using picture capture software over the simple, less accurate, (Alt+) Print Screen function of Windows OS.
  • Use the Windows Standard color scheme for images that need to be inserted in your document, so that a later update will be easier (no need to change all the pictures) and there will be no discrepancies between the images inserted in that document by (possibly) different persons.
  • Have as many fields as possible filled in the screen shots that you take, so that your readers receive enough relevant information.
  • You do not necessarily have to add images of the buttons that contain only text (e.g. OK, Cancel, Apply, Advanced, etc.). Just the button's name written with bold letters should suffice. Nevertheless, you should illustrate the image-buttons.
  • Do not insert the images directly from the picture capture software. Save them in a separate folder for further use.
  • Use diagrams when you want to illustrate the work-flow of the application or of one part of the application that you are documenting. Also, you can use diagrams to illustrate the structure or hierarchy of the different functionalities of the software.
  • Insert pictures after each step described in your document, and for each action that needs to be taken to obtain a specific result. It will be easier for your readers to follow the step-by-step approach.
  • Place a caption under each of the inserted pictures, so that the readers know what they are looking at.

· Proofreading
Go over the document once or twice, to make sure that the grammar you used is accurate, that you have spelled the words right, that you haven't skipped any important information and that you have formatted all your text properly.

· Insert the Table of Contents
Once you're sure that your text is OK, insert the table of contents. It is preferable that it has no more than 3 - 4 levels, but this depends on what you deem important and how obvious you want some information to be to your readers.

· Insert the Indexes
It is now time to index the most important terms and phrases in your document. Remember to update the table of contents afterwards.

· Send the Document to be Reviewed
After checking that everything is in order, table of contents, indexes and text altogether, send the document to one of the Subject Matter Experts (SME) for review. Ask that they use the Track Changes function, so that you can see exactly what they have modified and where you should concentrate your attention.

After you receive it back, you either have to go over some of the above-mentioned steps in order to correct possible errors or fill in some information gaps, or the document will be approved and you can forward it to the proper department so that it can be distributed to customers, and you can start working on the next document.

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

All in all, it is important to always keep in mind that communication is a key factor in the work of a technical writer. Communication with the technical writing team (where it exists), with the engineers, with the SMEs, with the deployment staff, the marketing staff, sometimes even with the programmers. This is the only way that a technical writer within a company can progress and evolve into a real professional.


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.


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…