Software documentation: Difference between revisions

Revision as of 14:06, 10 March 2024

Revision as of 09:30, 26 April 2024

Line 100:

# '''List or Reference:''' The final type of organizing principle is one in which commands or tasks are simply listed alphabetically or logically grouped, often via cross-referenced indexes. This latter approach is of greater use to advanced users who know exactly what sort of information they are looking for.

A common complaint among users regarding software documentation is that only one of these three approaches was taken to the near-exclusion of the other two. It is common to limit provided software documentation for [[personal computer]]s to [[online help]] that givegives only reference information on commands or menu items. The job of tutoring new users or helping more experienced users get the most out of a program is left to private publishers, who are often given significant assistance by the software developer.

==== Composing user documentation ====

Line 107:

# [[User analysis]], the basic research phase of the process.<ref>Barker, pg. 118.</ref>

# Planning, or the actual documentation phase.<ref>Barker, pg. 173.</ref>

# Draft review, is a self-explanatory phase where feedback is sought on the draft composed in the previous step.<ref>Barker, pg. 217.</ref>

# [[Usability testing]], whereby the usability of the document is tested empirically.<ref>Barker, pg. 240.</ref>

# [[Editing]], is the final step in which the information collected in steps three and four is used to produce the final draft.

=== Marketing documentation ===

For many applications it is necessary to have some promotional materials to encourage casual observers to spend more time learning about the product. This form of documentation has three purposes:

# To excite the potential user about the product and instill in them a desire forto becomingbecome more involved with it.

# To inform them about what exactly the product does, so that their expectations are in line with what they will be receiving.

# To explain the position of this product with respect to other alternatives.