Editing Software documentation (section)

=== User documentation ===
{{About|section=yes|consumable guides for software usage|more general systems|End user documentation}}
Unlike code documents, user documents simply describe how a program is used.

In the case of a [[Library (computing)|software library]], the code documents and user documents could in some cases be effectively equivalent and worth conjoining, but for a general application this is not often true.

Typically, the user documentation describes each feature of the program, and assists the user in realizing these features. It is very important for user documents to not be confusing, and for them to be up to date.  User documents do not need to be organized in any particular way, but it is very important for them to have a thorough [[Index (publishing)|index]]. Consistency and simplicity are also very valuable. User documentation is considered to constitute a contract specifying what the software will do. [[API Writer]]s are very well accomplished towards writing good user documents as they would be well aware of the software architecture and programming techniques used. See also [[technical writing]].

User documentation can be produced in a variety of online and print formats.<ref>{{cite book| url = http://dl.acm.org/citation.cfm?id=2775457| title = RH Earle, MA Rosso, KE Alexander (2015) User preferences of software documentation genres. Proceedings of the 33rd Annual International Conference on the Design of Communication (ACM SIGDOC).| date = 16 July 2015| pages = 1–10| doi = 10.1145/2775441.2775457| isbn = 978-1-4503-3648-2}}</ref> However, there are three broad ways in which user documentation can be organized. 
# '''Tutorial:''' A [[tutorial]] approach is considered the most useful for a new user, in which they are guided through each step of accomplishing particular tasks.<ref name=kdp>{{cite web
  | last = Woelz 
  | first = Carlos 
  | title = The KDE Documentation Primer
  | url = http://i18n.kde.org/docs/doc-primer/index.html
  | access-date = 15 June 2009 }}</ref> 
# '''Thematic:''' A [[Theme (literature)|thematic]] approach, where chapters or sections concentrate on one particular area of interest, is of more general use to an intermediate user.  Some authors prefer to convey their ideas through a knowledge based article to facilitate the user needs.  This approach is usually practiced by a dynamic industry, such as [[Information technology]].<ref name=kbad>{{cite web
  | last = Microsoft
  | author-link = Microsoft
  | title = Knowledge Base Articles for Driver Development
  | website = [[Microsoft]]
 | url = http://www.microsoft.com/whdc/driver/kernel/kb-drv.mspx
  | access-date = 15 June 2009 }}
</ref>
# '''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 gives 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 ====
Like other forms of technical documentation, good user documentation benefits from an organized process of development. In the case of user documentation, the process as it commonly occurs in industry consists of five steps:<ref>Thomas T. Barker, [http://www.writingsoftwaredocumentation.com/index.htm Writing Software Documentation], Preface, xxiv. Part of the [[Allyn & Bacon]] Series in Technical Communication, 2nd ed. [[Upper Saddle River, New Jersey|Upper Saddle River]]: [[Pearson Education]], 2003. {{ISBN|0321103289}} {{webarchive |url=https://web.archive.org/web/20130513033153/http://www.writingsoftwaredocumentation.com/index.htm |date=May 13, 2013 }}</ref>

# [[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.