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

2. 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. 3 January 31, 2008 3 Types of Documentation ● Architecture and design documents ● Technical documentation ● User documentation ● Marketing documentation

4. 4 January 31, 2008 4 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. 5 January 31, 2008 5 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. 6 January 31, 2008 6 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. 7 January 31, 2008 7 Marketing Documentation ● Describe product ● Why it is useful ● What it does ● When it is available ● Compare to other software

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

9. 9 January 31, 2008 9 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. 10 January 31, 2008 10 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. 11 January 31, 2008 11 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: ● http://library.gnome.org/devel/gdp-style-guide/ http://library.gnome.org/devel/gdp-style-guide/ ● http://www.mozilla.org/contribute/writing/guidelines http://www.mozilla.org/contribute/writing/guidelines ● http://i18n.kde.org/docs/styleguide/ http://i18n.kde.org/docs/styleguide/ ● http://fedoraproject.org/wiki/DocsProject/StyleGuide http://fedoraproject.org/wiki/DocsProject/StyleGuide

12. 12 January 31, 2008 12 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. 13 January 31, 2008 13 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. 14 January 31, 2008 14 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. 15 January 31, 2008 15 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. 16 January 31, 2008 16 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. 17 January 31, 2008 17 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. 18 January 31, 2008 18 Further Reading ● http://en.wikipedia.org/wiki/Software_documentation http://en.wikipedia.org/wiki/Software_documentation ● http://en.wikiversity.org/wiki/Technical_writing http://en.wikiversity.org/wiki/Technical_writing ● http://mcmanus.typepad.com/grind/2004/12/how_to_document.html http://mcmanus.typepad.com/grind/2004/12/how_to_document.html ● http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/ http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/