FSOSS - Enter the 4th Dimension: Documentation

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

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

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

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

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

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

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!

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

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

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

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

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

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

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?

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

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

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

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

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

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

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

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**

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

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

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

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

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

FSOSS - Enter the 4th Dimension: Documentation

More Related Content

What's hot (20)

Similar to FSOSS - Enter the 4th Dimension: Documentation (20)

Recently uploaded (20)

FSOSS - Enter the 4th Dimension: Documentation