Project Documentation

Link to OSCON page.

What is documentation

• first contact with a user

• source of education

• front line of suppport

• consists of

  • conceptual material

  • “how-to”

  • reference material

  • troubleshooting

• communication with people who care about your project

Things to avoid

• Perfection

  • release early and often

• forgetting that your audience is people

qualities of solid documentation

• complete

  • covers all features, usage modes, and interfaces

  • answers essential questions

    • who what where

• correct

  • should match the software, hardware, or device

  • logically organized

  • consistent and professional

• appropriate

  • know who your audience is

    • know what they need to know

    • answers their questions

  • accessible

  • consistent and professional

• what is less important

  • text formats

  • tools

  • delivery format

    • consider mobile devices

  • perfection

• what is not solid

  • missing unmentioned features

  • inconsistent

  • unprofessional

    • grammar, spelling, etc

classical elements of technical documentation

• concepts – what?

  • The 10,000ft overhead view

  • overview

  • brochures, white papers

  • architecture guides

  • focus on education

• Tasks and examples – how?

  • The 10ft overhead view

  • step-by-step guides

  • quickstart guides

  • tutorials

  • training materials

  • focus on usability and consistency

• Reference

  • the 0ft view

  • system reference manuals

  • API guides

  • layout and manufacturing guides

  • maximal cross-references

  • focus on completeness

• troubleshooting

  • the -6ft view, looking up
    

    • when you get here, you've dug yourself in a hole

  • step-by-step diagnostics

  • flowcharts

  • FAQs

  • from the reader's perspective

  • focus on answering questions

readers you must satisfy

• partners

  • sell, extend, promote, or add value to your project

• developers

  • use your project as a basis to start they're own project

• internal

  • inside our organization

• end-users

  • use the end result (and sometimes pay for the privilege)

• community

  • care about your product by choice

critical questions about documentation

• what is it

• why do I need it

• what does it look like

• who's going to make it

• where do I put it

• when do I schedule it

good documentation habits

• be proactive

• begin with the end in mind

• put first things first

• think win/win

• seek first to understand, then be understood

• synergize (buzzword alert)

• sharpen the saw (practice)