This presentation for the Free Software and Open Source Symposium at Seneca College in 2012 shows how good documentation benefits all open source projects.

1. Beyond MAN Pages
3 Things to Make your Open
Source Project a User Favourite
Beth Agnew
FSOSS 2011

2. Overview
 My brief bio
 Involve users throughout life cycle
– Documentation
– Usability
– Publicity
 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
Involve user community (or a representative user) at every stage

5. Requirements &
Planning
Specifications & Design
Construction / Code / Development
Testing
Implementation
Maintenance
Project Life Cycle
Design and Plan Develop (Write) Review & Edit
Publish and
Maintain

6. Documentation
Stock photo

8. 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!

9. Open Source Approach
 Traditionally, MAN pages, PDFs and
printed docs
 Now, fluid, collaborative
documentation: FAQs, wikis, EPUBs.
 Community meshes interests and
expertise, covers all the bases
 Allows browsing and searching
 Allows publishing in multiple media

10. Usability
Stock photo

11. User Focus
 Who is the audience?
–End users
–Other developers
–Multiple audiences
–Combination audiences
–5W1H (who, what, when, where, why, how)

12. 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?

13. Publicity
Stock photo

14. Social Media
 Provide ways to interact with your
community
 Provide ways for your community to share
info
 Provide a place for your community to
gather
 Provide a conversation for the community
to participate in

15. Shameless Plug
By Mike O’Dowd

16. 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

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

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

19. Unforgettable Projects
 Work really well, transparently
 Provide excellent user support
 Have a thriving community
 Engage users and developers
 Leverage comments and feedback
 Continue to improve and prosper

20. Recap
 Develop project to audience NEEDS
 Clear, concise documentation
 Good usability (achieve goals)
 Get the word out – social media
 Get documentation help if needed
 Make the project unforgettable

21. By Paul Henman

22. Open Source
 A community coming together
 Many people creating a dialogue
about issues
 A collective search for solutions
 Inclusive rather than exclusive
 Adjusts as necessary on the fly
 Doesn’t harm established companies,
except where they are too greedy

23. #Occupy
 A community coming together
 Many people creating a dialogue about issues
 A collective search for solutions
 Inclusive rather than exclusive
 Adjusts as necessary on the fly
 Doesn’t harm established companies, except where they are too greedy
http://occupyto.org/
Used with permission

24. Questions?