People search for information in technical documents when they need to know something. They might want to learn about the system, solve a problem, perform a complicated task or configure the behav- ior of the system. People look for the documentation only when they need to, and they often have limited time and patience for finding the required information. Unfortunately, when people have bad ex- perience with the technical documentation, they generally begin to regard the documentation as unhelpful and unusable. If they do not manage to find particular information or, on the other hand, they find a topic about their problem which does not help them with their task, they lose interest in the documents.
Therefore, the technical information needs to have certain quali- tative characteristics, so that it can benefit and not frustrate the users of the software. According to [12], quality technical information can
5. SOFTWARE DOCUMENTATION be characterized by three groups of values with the following char- acteristics: • Easy to use – Task orientation – Accuracy – Completeness • Easy to understand – Clarity – Concreteness – Style Easy to find – Organization – Retrievability – Visual effectiveness
Writing task-oriented technical instructions is essential in agile envi- ronment. Therefore, a whole sub-chapter is dedicated to this charac- teristic, while other characteristics are explained only briefly.
5.3.1 Task Orientation
Task-oriented writing focuses on aiding users with their tasks. It is often important to explain to the users how a product works and how it is structured, but this information rarely helps the users di- rectly with accomplishing their goals. Feature oriented documenta- tion approach, which encompasses writing descriptions of the prod- uct, explaining the product’s features and elements of the user inter- face, corresponds with the traditional development methodologies. In the Waterfall model, the documentation is produced at the end of the project, separately from the development process. It is not cre- ated in a close collaboration with the product creators and thus is focused more on what can be done with the product instead on what the users actually need to do with the product.
5. SOFTWARE DOCUMENTATION Instead, it is more useful to provide the users with practical in- structions on how to perform individual tasks with the product. To determine the most important tasks the users will need to perform, the Technical Writers need to be familiar with the target users’ envi- ronment and conditions. Tasks with clearly written instructions and steps help users quickly accomplish what they need. This approach is favored by agile methodologies, as it corresponds with task-oriented recording of requirements in the form of user stories.
The next level of task-oriented documentation writing is workflow- oriented documentation, as suggested by Leah Guren in [11]. This approach not only emphasizes structuring the information in tasks but also promotes logically connecting the tasks into workflows. Work- flows can be understood as sequences of tasks that need to be per- formed chronologically to achieve a certain goal or as circumstances in which the users perform the tasks. This approach, however, re- quires even broader knowledge of the audience and their needs, and deeper understanding of the documented system.
5.3.2 Other Characteristics
Accuracy means that the technical information is correct and free of errors. Users of the software rely on the accuracy of the documenta- tion and may lose their trust in it if they encounter information that is incorrect. Therefore it is a good practice to have SMEs check the documentation for technical accurateness and to closely follow the development of the product to keep the documentation up-to-date.
The technical documentation must contain all the necessary in- formation on the subject. It is, however, important to determine the ideal amount of information which should be included in individual topics. Too little information may frustrate the users, when they do not find the information they need. Too much information though, may overwhelm the users and make the particularly sought infor- mation impossible to find.
Clear information enables the users to understand the written text the first time they read it. The language in which the informa- tion is written is simplified and does not contain complex structures and vague descriptions.
5. SOFTWARE DOCUMENTATION of the product are brought closer to the user by using appropriate ex- amples, analogies and illustrations.
Style defines writing conventions that the writers in the company should adhere to. Such standards cover the tone in which the text is written, grammar and spelling and other editorial choices. They enable Technical Writers to write with the regards to the corporate identity and help the users receive the information they expect.
Organizing the information in a logical and predictable way is another important trait of technical documentation. It applies to or- ganizing the topics into structures as well as arranging the informa- tion inside individual topics. The information should be organized consistently to allow for easy navigation.
Retrievability means that information in technical documentation is easy to find. It is important to ensure that the users do not get lost while searching for specific information and that they find it quickly and by using various approaches.
Visual effectiveness implies that the visual elements in the doc- umentation complement the text and highlight important informa- tion. Illustrations clarify significant concepts that would be difficult to comprehend from text and provide examples of usage of the prod- uct. Visual effectiveness also influences all other characteristics of quality technical information and thus need to be in balance with them.
5.4 Documentation in Traditional Development
Environment
In traditional Waterfall approach to software development, docu- mentation is created mainly at the beginning and end of the project, as illustrated on figure 5.1. At the beginning, requirement specifi- cations are created in the form of documents describing the project to be developed, its features, attributes and behavior. Architecture and design documents define visual and construction principles to be used in the product. Project plan states what and when will be finished and test plan what, when and how will be tested.
The disadvantage of creating heavy project documentation at the beginning is that it is difficult to capture all properties of the product
5. SOFTWARE DOCUMENTATION
Figure 5.1: Documenting heavily at the beginning and end of the project (source [15])
before its implementation begins. Consequently, these documents of- ten become outdated as soon as they are created [15].
Technical Writers in traditional methodologies create user docu- mentation at the end of the project, after the product has been de- veloped. This approach brings advantages as well as disadvantages. The advantage is that the user documentation can be provided as a service, either by the company’s separate documentation team or by outsourcing. When the product is completed, the Technical Writers can explore it with all its provided features, finished user interface and unchanging environment.
The problem is, that often this is not enough and the Technical Writers also need to obtain information from the Subject Matter Ex- perts (SMEs), who may be hard to reach after the development phase is finished or may not remember important details from the product implementation. Another difficulty is that the time needed to cre- ate the user documentation further extends the overall time of the project and thus postpones the product release. This fact also puts stress on the Technical Writers to finish the documentation in the
5. SOFTWARE DOCUMENTATION scheduled time.