Software Business

• 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.

• 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.

• 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.

You can also bookmark and share this article: