Content

• Steps
• Method 1 of 2: Writing software documentation for technical users.
• Method 2 of 2: Writing Programming Documentation for End Users
• Tips
• What do you need

Good software documentation - whether it is a requirements specification document for programmers or testers, a technical document for internal users, a software manual, or a user help file - helps the person working with the software understand its features and functions. Follow the tips on how to write software documentation for technical and end users.

Steps

Method 1 of 2: Writing software documentation for technical users.

1. 1 Determine what information should be mentioned. Software requirements documents serve as a reference guide for user interface designers, programmers who write code, and testers who verify that software is working as expected. The exact information depends on the program itself, but may include the following:
   • Key files in the application. These can be files created by the development team, databases called during a program operation, and third-party utilities.
   • Functions and subroutines. It specifies what each function and subroutine does, including the inputs and outputs.
   • Programmatic variables and constants and how they are used in the application.
   • General structure of the program. For disk-based applications, you will probably need a description of the individual blocks and libraries of the program, while for web applications you will need a description of the pages that use the files.
2. 2 Decide how much documentation should be in the code and how much should be segregated. The more technical documentation is written in code, the easier it will be to update that code, as well as the documentation for different versions of the original application.At a minimum, the documentation in the program code should explain functions, subroutines, program constants, and variables.
   • If the code is quite long, you can format it as a help file where you can search for keywords or indexes. This will be a big plus for applications where the logic of the program is divided into many pages and includes numbers of auxiliary files, as in certain web applications.
   • Some programming languages, such as Java or the NET Framework (Visual Basic .NET, C #), have their own standards for documentation code. In such cases, follow the standard guidelines for how much documentation to include in your code.
3. 3 Choose the right tool. To some extent, this is determined by the language in which the code is written, be it C ++, C #, Visual Basic, Java, or PHP - each has its own tool. In other cases, the tool used is determined by the type of documentation required.
   • The Microsoft Word text editor is a suitable tool for creating separate text-based documentation files that are simple and concise. For long text files, many technical writers prefer to choose Adobe FrameMaker.
   • Help files for documenting programming code can be written using any tool such as RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare, or HelpLogix.

Method 2 of 2: Writing Programming Documentation for End Users

1. 1 Define business considerations for your documentation. While the functional reasons for software documentation are to help users understand how to use an application, there are other reasons, such as helping to market a product, improving a company's image, and most importantly, reducing support costs. In certain cases, documentation is required to comply with certain rules and legal requirements.
   • By no means should software documentation replace poor interface design. If the application screen requires a lot of explanatory documentation, then it is better to change the design to something more intuitive.
2. 2 Understand the audience you are writing documentation for. In most cases, software users know little about computers beyond the tasks of the application. There are several ways to determine how to align their needs with the documentation.
   • Look at the professions your potential users own. The system administrator is more likely to be an expert in using software applications, while the data entry operator is more likely to own the application that he or she is currently using to enter data.
   • Look at the users themselves. While their positions generally define what people do, there are significant differences in how certain positions are used in a given organization. After interviewing potential users, you can add your opinion - whether the title of the position corresponds to the duties performed.
   • Have a look at the existing documentation. Documentation for previous versions of the software gives a rough idea of ​​what the user needs to know about using the software. However, remember that end users are not interested in how the program works, it is important for them to know what they can do with it.
   • Determine the tasks that are required for this job and what tasks must be completed before these tasks can be completed.
3. 3 Determine the appropriate format (s) for the documentation. Software documentation can be structured in one of two formats - reference manual and instruction manual. Sometimes it is better to choose a mixed version of the two formats.
   • The reference manual is intended to explain the software toolbox (buttons, tables, field, and dialog bar) and how the toolbox works. Many help files are written in this format, and contextual hints help show the desired topic after the user clicks the help button on the desired screen.
   • The user manual explains how to use the software for a specific task. The instructions for use are often in the form of a printed manual or PDF format, although some help files include topics on how to perform a specific task. (These help topics are usually not contextual, although they may be hyperlinks.) Instructions for use are often in the form of a reference book with a task description and step-by-step instructions.
4. 4 Decide what format (s) the documentation should be. End-user software documentation can be in one or more formats: printed manual, PDF documents, help files, or online help. Each of these formats is designed to show the user how to use each software function, be it a quick tour or a tutorial. As with help files and online help, the documentation can have a demo video or text with pictures.
   • The hint files and online help should be indexed, searchable by keywords, allowing the user to quickly find the information they are looking for. While the tooltip file tools can automatically generate indexes, it is best to do so manually using terms that users are likely to search for.
5. 5 Choose the right tool for creating documentation. Printed manuals or PDF format can be written in text editors such as Word or FrameMaker, depending on the length and complexity of the manual. Help files can be written using development tools such as RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix, or HelpServer.

Tips

• The text should be easy to read, pictures should be placed as close as possible to the text to which they refer. Divide the documentation into sections and logical topics. Each section or topic should address a specific issue, be it one program or task. Related questions should be labeled "See also" with a hyperlink if required.
• All the tools for creating documentation that were listed above can be supplemented with a screenshot program, for example "Snagit", if the documentation requires a certain number of screenshots. As with other documentation, screenshots should explain how the software works, not mislead the user.
• The tone of writing the documentation is also very important, especially if it is written for end users. Use the second person “you” instead of the third person “users”.

What do you need

• Documentation tool / development tool
• Screenshot tool