Writing Software Documentation

Documentation



The size is critical in enhancing readability. It should not be too small. However, the size should not be too big as well. This may lead to unequal proportions which would also be difficult to read. Making the font bold would help for emphasis. Italicizing letters would also help to get attention of readers. Underlining words can help in highlighting important points. It is best to use black color for the written content and a white background for the document.

    Define active voice, simple language, redundancies, and abbreviations

Active voice refers to a grammatical point of view where the clauses has a transitive verb that is nominative in nature. This means that the noun who did the action is usually the subject. This format is used a lot of times in different settings. In terms of documentation, it means that the sentences are focused on the subject matter. Ownership can usually be seen for emphasis on expertise and believability.

Simple language refers to the use of basic words in sentence structures. Complex and seldom used words should be avoided if possible. The language should be straight to the point and each texts should be easy to understand. Everything should be explained in layman's term.

 A redundancy is a repetition of words or ideas in a situation. If applied in documentation, it means that the same instructions or concepts are being used repeatedly.

 Abbreviations are usually shortened forms of a group of words. Usually the initials of each words are used. It could also be applied to a word through applying only the first few letters to make it shorter.

    Discuss the recommended process for writing the first draft of a manual

 The first draft of a manual should contain the important instructions in using a specific material, learning a specific topic, or handling a technology. The organization and format of each subject should already be shown. This would serve as a basis for future drafts. An outline should be created. This should show clear distinctions between the different parts of the manual. The focus of each topic included in the documentation should be summarized.

Part II

The help document of google docs showed good strength in terms of content design. Its features are appropriately aligned to the usage of the mentioned web application.

Meets the user's needs

    The authors used an intuitive outline form.

    The user can browse through different topics easily.
 
    The design made the outline look clear and organized.

    If a user wants to find help in a specific part of the application, he can browse on each topic with ease and would be able to find a subject that matches his search interest.

 Does not meet user's needs

    The document focused its emphasis on the basic features.

    Some specific information are included but looking for them would be difficult.

    Search feature or indexing for specific words is not included.

List of changes

    Add an effective search or indexing systema

    Expand the outline to emphasize focus on specific subjects

    Specific and more technical terms should have their own section

Part III
 
The changes would make the efficient outline easier to use. It would allow people to look for specific terms. Although the outline made it easier to navigate and look for the basic information regarding the web application, it would be difficult for more technical users to actually use the help document. Things such as shortcuts and hotkeys need to be mined further in order to get the needed topic. A search or indexing tool should be available for the users.

The help document has an effective outline but it still needs further expansion. This should be done to accommodate the needs of more technical users who need specific information. The expansion could include a special part where the more technical features can be discussed. This would allow people to easily look for it in the outline. The format is currently at two levels, with a third one that could be accessed further. This should be included in the main outline. Aside from that, the overall outline should be included at the top part of the help document. This would make it easier for users to look for the features they need in the program.

A list of terms should be included for better navigation. Important terms should be listed, similar to an appendix. This would allow users to get acquainted about specific words and then be able to browse directly to the page they need. This would also be helpful in case someone wants to know a certain feature but does not know where to look at.

The changes made great improvements on the revised section. Users can easily navigate between the outlines. They could find specific features easily. In case users do not know the right words to search, they can go directly to a list of terms. The navigation is simpler and the system of acquiring knowledge is faster and more accurate.
 
Part IV

Technical software documents should let users know what happens when certain actions are done. This includes the specific function of each buttons or inputs. In order to have a better experience for the users, there should be a tutorial prompt at the beginning of the software. This could be closed right away if a person is already aware of the system's functions. Aside from that, the prompt should be repeated again at the last input instruction. This would remind the user of the effects of their actions.