Your Open Source Software project needs good documentation to create a superb user experience.

1. Enter the 4th
Dimension -
Documentation
Creating a superb user
experience

2. Overview
 Creating good documentation
 Building intelligence into the project
– Intuitive interfaces
– Error prevention
– Informative error messages
– Performance support
 Technical Communication Help
 Delivering a superb user experience

3. Bio
 Seneca Tech Comm – Co-ordinator
 Veteran Techwriter
 Blogger, Vlogger
 Gamer
 www.senecatechcomm.com

4. A Reminder…
 Project Life Cycle
1. Planning
2. Design
3. Development
4. Implementation
5. Maintenance

5. Requirements &
Planning
Specifications &
Design
Construction /
Code / Development
Testing
Implementation
Maintenance
Design and Plan Develop Review
Publish and
Maintain
Project Life Cycle
Where documentation fits in

6. Stages in the
documentation
processDevelop
Design and
Plan
Review
Publish and
Maintain
• Research project
• User/task analysis
• Select media
• Write outline
• Develop plan
• Develop a prototype
• Estimate time, costs,
resources required
• Develop schedule
• Review
• Get approval
• Research
• Test product
• Write
• Layout
• Build navigation
tools (index,
searches, Table
of Contents, etc)
• Develop
illustrations,
screen shots,
samples
• Test
documentation
• Proofread
• Peer review
• Edit
• Distribute for
review
• Collect review
comments
• Conduct review
meetings
• Revise
• Repeat as
necessary
• Produce final
materials
• Oversee printing,
if needed
• Distribute
• Collect changes
for next version

7. Why documentation?
 Users enjoy using the software
– Therefore more users
 Developers can access the code
– Therefore better collaborative
development
 Support liabilities are reduced
– Therefore lower support needs/costs
= More successful projects!

8. More info = fewer bugs
 Documentation at the specifications
and design stage
 Documentation during development
 Documentation for end users
 Documentation for customer support

9.  Fixing at front end
vs. back end
Cost of Bugs
Specifications & Design Stage
Devt & QA Testing Stages
Delivered to Customer

10. Good Documentation is…
 Clear
 Concise
 Correct
 Complete
 Consistent
 Convenient

11. Open source approach
 Traditionally, PDFs and printed docs
 Now, fluid, collaborative
documentation: FAQs, wikis, etc.
 Community meshes interests and
expertise, covers all the bases
 Allows browsing and searching
 Allows publishing in multiple media

12. Collaborative Docs
 Wiki advantages:
– Anyone can contribute
– Multiple editors and reviewers
– Good bug fixing!
– Leverage strengths and expertise
 Wiki disadvantages:
– Ownership & responsibility
– Authority, “writing by committee”
– Unintentional sabotage

13. User Focus
 Who is the audience?
–End users
–Other developers
–Multiple audiences
–Combination audiences

14. Task Focus
 Task based vs. Feature based
 Users want to accomplish tasks
 Developers are enamoured of
features
 What makes sense in your context?
– End user docs or API?

15. Techniques
 Drafts – iterative development
– Wiki, with RSS feed for
changes/maintenance
 Reviews – stakeholders
 Approvals – “official” signoffs
 Backups – history and rollbacks
 Publishing – distribution
 Maintenance – subsequent changes

16. Artifacts
 Planning docs
 Specifications
 Use cases
 User stories
 Commented code
 Developer notes
 Release notes, readmes

17. Intuitive Projects
 Interfaces contain information
– Labels, examples, tooltips
 Error prevention
– Best practices, one correct way
 Informative error messages
– What happened and how to recover!
 Performance support
– Support task completion, workflows

18. Validate Input
 Use masks and examples
– dd/mm/yyyy
– 42/23/8 should not be allowed
– Phone numbers, postal codes, credit
card numbers
– Automatic tabbing

19. User Support

20. Support Searching
 Brainstorm terminology
– Synonyms
– Alternate forms of terms
• print, printing, printer
 Organization & Structure
– Logical, task-based

21. Watch out for:
 Code drift
– If the code that you have included in
your documentation changes, be sure to
update the docs
 Scope creep
– Constrain the scope of the project so
you have time to complete the docs
 Broken links
– Make sure linked articles don’t get lost

22. Watch out for:
 “It works on my machine!”
 Overloading volunteers – single
pages rather than all of it
 Managing user input - comments

23. Change Control
 Version Control – similar to source code
 Bug database – make sure the doc
writers have access*
 Flag items that need:
– Updated documentation when fixed
– Doc fix instead of a code fix
 Prioritize doc fixes in the same way
as bug fixes**

24. Techwriters
 Core competencies
– Communication, Localization, Internationalization
– Collaboration
– Technical affinity
• Self-taught, get quickly up to speed
– User affinity
• Put themselves in the user’s place
–Single-sourcing (DITA, DocBook, XML)
–Project management

25. Techwriters
 Core competencies cont.
– Writing in plain language
– Simplifying complex concepts
– Organizing and structuring information
– Researching users and software
products
– Interviewing SMEs

26. SMEs
 Subject Matter Experts
– Should focus on what they do best
– Often cannot explain things simply
– Benefit from Techwriters who have skills
to extract information from them
Back to the Future, 1985

27. Techwriters
 Join project early
 Advocate for users
 Work closely with developers
 Create documentation
– PDFs, online help, FAQs, etc.
 Perform user testing
 Assist with QA, Customer Support &
Marketing

28. Successful Projects
 Have good documentation
 Are well received by users
 Are well supported by developer
communities
 Lead to more opportunities

29. Questions?