Writing technical documentation
How to Write Software Documentation
Good software documentation, whether a specifications document for programmers and testers, a technical document for internal users, or software manuals and help files for end users, helps the person working with the software understand its features and functions. Good software documentation is specific, concise, and relevant, providing all the information important to the person using the software. Following are instructions on how to write software documentation for technical users and end users.
Writing Software Documentation for Technical Users
Determine what information needs to be included.Software specification documents serve as reference manuals for designers of the user interface, programmers who write the code, and testers who verify that the software works as intended. The exact information depends on the program in question but may include any of the following:
- Key files within the application. This may include files created by the development team, databases accessed during the program's operation, and third-party utility programs.
- Functions and subroutines. This includes an explanation of what each function or subroutine does, including its range of input values and output values.
- Program variables and constants, and how they're used in the application.
- The overall program structure. For a disc-based application, this may mean describing the program's individual modules and libraries, while for a Web application, this may mean describing which pages use which files.
Decide how much of the documentation should be within the program code and how much should be separate from it.The more technical documentation is developed within the program's source code to begin with, the easier it will be to update and maintain along with the code, as well as to document various versions of the original application. At a minimum, documentation within the source code needs to explain the purpose of functions, subroutines, variables, and constants.
- If the source code is particularly lengthy, it can be documented in the form of a help file, which can be indexed or searched with keywords. This is a particular advantage for applications where the program logic is fragmented over many pages and includes a number of supplemental files, as with certain Web applications.
- Some programming languages, such as Java and the .NET Framework (Visual Basic.NET, C #), have their own standards for documenting code. In these cases, follow the standards as to how much of the documentation should be included with the source code.
Choose the appropriate documentation tool.To some extent, this is determined by the language the code is written in, be it C++, C#, Visual Basic, Java, or PHP, as specific tools exist for these and other languages. In other cases, the tool to use is determined by the type of documentation required.
- Word-processing programs for Microsoft Word are adequate for creating separate text files of documentation, as long as the documentation is fairly short and simple. For long, complex text files, many technical writers prefer a documentation tool such as Adobe FrameMaker.
- Help files for documenting source code can be produced with any help authoring tool, such as RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare, or HelpLogix.
Writing Software Documentation for End Users
Determine the business reasons for your documentation.Although the functional reason for documenting software is to help users understand how to use the application, there are other reasons as well, such as assisting in marketing the software, enhancing the company image, and most notably, reducing technical support costs. In some cases, documentation is necessary to comply with certain regulations or other legal requirements.
- In no case, however, should software documentation substitute for poor interface design. If an application screen requires reams of documentation to explain it, better to change the screen design to something more intuitive.
Understand the audience you're writing the documentation for.In most cases, software users have little knowledge of computers outside of the tasks the applications they use enable them to do. There are several ways to determine how to address their needs with your documentation.
- Look at the job titles your prospective users hold. A system administrator is likely expert with a number of software applications, while a data entry clerk is more likely to know only the application he or she currently uses to enter data.
- Look at the users themselves. Although job titles generally indicate what people do, there can be considerable variation in how certain titles are used within a given organization. By interviewing prospective users, you can get a feel for whether your impressions of what their job title indicates are accurate or not.
- Look at existing documentation. Documentation for previous versions of software, as well as functional specifications, provide some indication as to what the user will need to know to use the program. Keep in mind, however, that end users are not as interested in how the program works as they are in what it can do for them.
- Identify the tasks needed to do the job, and what tasks need to be done before those tasks can be done.
Determine the appropriate format(s) for the documentation.Software documentation can be structured in 1 of 2 formats, the reference manual and the user guide. Sometimes, a combination of formats is the best approach.
- A reference manual format is devoted to explaining the individual features of a software application (button, tab, field, and dialog box) and how they work. Many help files are written in this format, particularly context-sensitive help that displays a relevant topic whenever a user clicks the Help button on a particular screen.
- A user guide format explains how to use the software to perform a particular task. User guides are often formatted as printed guides or PDFs, although some help files include topics on how to perform particular tasks. (These help topics are usually not context-sensitive, although they may be hyperlinked to from topics that are.) User guides often take the form of tutorials, with a summary of the tasks to be performed in the introduction and instructions given in numbered steps.
Decide what form(s) the documentation should take.Software documentation for end users can take 1 or several of many forms: printed manuals, PDF documents, help files, or online help. Each form is designed to show the user how to use each of the program's functions, whether in the form of a walkthrough or a tutorial; in the case of help files and online help, this may include demonstration videos as well as text and still graphics.
- Help files and online help should be indexed and keyword-searchable to allow users to quickly find the information they're looking for. Although help file authoring tools can generate indexes automatically, it is often better to create the index manually, using terms users are likely to search for.
Choose the appropriate documentation tool.Printed or PDF user manuals can be written with a word-processing program like Word or a sophisticated text editor like FrameMaker, depending on their length and complexity. Help files can be written with a help authoring tool like RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix, or HelpServer.
QuestionAre there any free tools for software documentation?wikiHow ContributorCommunity AnswerTry Doxygen. You comment your code, run Doxygen, and you have a webpage. Add LaTeX, and you have a PDF.Thanks!
I have seen keypresses documented in multiple formats. Is there an actual standard for items or are they all different?
What would the best directory structure be for an app's documentation?
What is the best way to write a documentation on IoT project?
- The text should be arranged for easy reading, with graphics placed as close to the text that refers to them as possible. Break the documentation down into sections and topics logically. Each section or topic should address a single issue, be it a single program feature or task. Related issues can be addressed with "see also" listings or hyperlinks as necessary.
- Any of the documentation tools listed above can be supplemented with a screenshot-creating program, such as Snagit, if the documentation requires a number of screenshots. As with other documentation, screenshots should be included to help explain how the software works, not to dazzle the user.
- Tone is particularly important, especially when writing software documentation for end users. Address users with the second person "you" instead of third person "users."
Things You'll Need
Software documentation tool/help authoring tool
Sources and Citations
- Rodney Ruff, Omaha, NE; experience as technical writer/help file author since 1997
In other languages:
Español: , Русский: , Português: , Deutsch: , Français: , Bahasa Indonesia:
Video: Software Documentation
People on Twitter are realising that wedding dresses with pockets exist
This Is What Its Really Like To Be In A Sexless Marriage
How to Dethatch a Lawn
Venice Film Festival 2019: The best red carpet style
Conor McGregor Mocks The Wrong Mayweather In Fight Announcement
Trouble Getting Pregnant
Why art is the hot new trend in luxury property
The Great Comic Relief Bake Off – who’s taking part
How to Select Hearing Protection
6 Times to Wear Lipstick (And 4 Times You NeverShould)
Kate Middletons Favorite Sneakers Are 31 Off for Amazon Prime Day
Top 22 Hair Care Blogs You Should Know About
How to Follow Jesus