1 January 31, Documenting Software William Cohen NCSU CSC 591W January 31, 2008

2 2 Need for Documentation ● Requiring people to study code for information not efficient ● Some programs very large and complex ● Not everyone may understand the code ● Documentation provides quicker way to understand the code and how to use it ● Documentation can impact usability of software

3 January 31, Types of Documentation ● Architecture and design documents ● Technical documentation ● User documentation ● Marketing documentation

4 January 31, Architecure and Design Documents ● Written early in the software development for: ● Entire project ● Specific feature or enhancement ● Describe planned implementation ● Compare different approaches ● Keep focus how to (or not to) do things

5 January 31, Technical Documentation ● Provide information for developers ● Examples: ● Documents describing layout of code in project ● Information about what routines are available in library ● Technical documentation may be extracted from source code: ● Keeps information close to implementation ● Regenerate documentation when code changes ● Automated tools for this: ● Doxygen ● Javadoc ● ROBODoc

6 January 31, User Documentation ● How to use the software ● Different user documentation for different purposes: ● Tutorials: short, introductory guides ● Thematic: group items by chapters ● Reference: describe everything, various organization: ● Alphabetical ● Logically grouped ● Indexes

7 January 31, Marketing Documentation ● Describe product ● Why it is useful ● What it does ● When it is available ● Compare to other software

8 January 31, Writing ● Audience ● Grammar ● Style Guides ● Organization and Structure ● Media

9 January 31, Audience ● The people reading the documentation may be very different than the programmers (e.g. Graphic designer using drawing program) ● Take time to explain needed background material ● Have idea what things are of interest to audience: ● Might focus on a few key operations ● May not be interested in a complete history of the project ● May not be interested in every possible option software has

10 January 31, Grammar ● Use accepted written grammar: ● Traditional spelling of words ● Complete sentences ● Appropriate paragraphs ● Slang and SMS or instant messaging abbreviations should be avoided ● Non-native speaker may have difficult understanding ● Translation might be difficult

11 January 31, Style Guides ● Companies and large projects have style guides ● Provide a consistent voice for the documentation ● Use consistent terminology to avoid confusion ● Describe writing conventions to allow mechanical generation of documents (e.g. Html and web) ● Example style guides: ● ● ● ●

12 January 31, General Style ● Be clear: chose words and phrases to avoid ambiguity ● Be accurate: explain how the software operates, not how you wished it worked ● Be concise: quicker people understand the more likely they are to use the software ● Be consistent: use the same agreed upon terms throughout the document ● Use active voice when possible ● Use present tense when possible

13 January 31, Organization and Structure ● Organization: ● Ordered steps ● Grouped by task ● Alphabetically ● Example document sections: ● Front matter: ● Preface, table of contents ● Introduction ● Body of documentation: ● Chapters or sections ● Glossary ● Appendices ● Index

14 January 31, Indexing ● Faster people can find needed information the better ● Possible items for index: ● Definitions ● Restrictions ● Acronyms ● Commands ● Command qualifiers ● Routines ● Data structures ● Key functions ● Procedures and tasks ● Tips, notes, and cautions ● Examples, tables, and figures

15 January 31, Ways of presenting information ● Prose and sentences ● Lists ● Tables ● Figures ● Graphics ● Screen shots ● Animation: show a sequences of steps ● Difficult to convert to printed form

16 January 31, Media ● Want to use the same content in multiple places ● Do not want to have multiple copies of content ● Tools such as DocBook generate multiple versions: ● Printed version ● Web version

17 January 31, Editing and Revision ● Use revision control system on text to track changes ● Read out loud to check ● Use tools to check spelling, formating and URL links ● Have other people read document: ● Everyone for understandable writing ● Developers for accuracy ● Target audience for missing or assumed information

18 January 31, Further Reading ● ● ● ●