FSOSS 2011 Beyond MAN Pages


Published on

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

Published in: Technology, Business
  • Be the first to comment

  • Be the first to like this

No Downloads
Total Views
On Slideshare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • Dialogue: an exchange of ideas or opinions on a particular issue, especially a political or religious issue, with a view to reaching an amicable agreement or settlement. Conversation: informal interchange of thoughts, information, etc. in a social context
  • Paul Frields started off getting involved with Linux because he wanted to contribute to documentation (unpaid). A few years later, he was such an expert on Linux that he was invited to be the Fedora project leader (well paid). Writing documentation for an open source project can be your entrée into nice paid positions in the software industry.
  • FSOSS 2011 Beyond MAN Pages

    1. 1. Beyond MAN Pages3 Things to Make your OpenSource Project a User FavouriteBeth AgnewFSOSS 2011
    2. 2. Overview My brief bio Involve users throughout life cycle– Documentation– Usability– Publicity Technical communication help Delivering a superb user experience
    3. 3. BioSeneca Tech Comm – Co-ordinatorVeteran TechwriterBlogger, VloggerGamerwww.senecatechcomm.com
    4. 4. A Reminder… Project Life Cycle1. Planning2. Design3. Development4. Implementation5. MaintenanceInvolve user community (or a representative user) at every stage
    5. 5. Requirements &PlanningSpecifications & DesignConstruction / Code / DevelopmentTestingImplementationMaintenanceProject Life CycleDesign and Plan Develop (Write) Review & EditPublish andMaintain
    6. 6. DocumentationStock photo
    7. 7. Why documentation? Users enjoy using the software– Therefore more users Developers can access the code– Therefore better collaborativedevelopment Support liabilities are reduced– Therefore lower support needs/costs= More successful projects!
    8. 8. Open Source Approach Traditionally, MAN pages, PDFs andprinted docs Now, fluid, collaborativedocumentation: FAQs, wikis, EPUBs. Community meshes interests andexpertise, covers all the bases Allows browsing and searching Allows publishing in multiple media
    9. 9. UsabilityStock photo
    10. 10. User Focus Who is the audience?–End users–Other developers–Multiple audiences–Combination audiences–5W1H (who, what, when, where, why, how)
    11. 11. Task Focus Task based vs. Feature based Users want to accomplish tasks Developers are enamoured offeatures What makes sense in your context?– End user docs or API?
    12. 12. PublicityStock photo
    13. 13. Social Media Provide ways to interact with yourcommunity Provide ways for your community to shareinfo Provide a place for your community togather Provide a conversation for the communityto participate in
    14. 14. Shameless PlugBy Mike O’Dowd
    15. 15. 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
    16. 16. Techwriters Core competencies cont.– Writing in plain language– Simplifying complex concepts– Organizing and structuring information– Researching users and softwareproducts– Interviewing SMEs
    17. 17. 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 &MarketingPaul Frields
    18. 18. 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
    19. 19. 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
    20. 20. By Paul Henman
    21. 21. Open Source A community coming together Many people creating a dialogueabout 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
    22. 22. #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 greedyhttp://occupyto.org/Used with permission
    23. 23. Questions?
    1. A particular slide catching your eye?

      Clipping is a handy way to collect important slides you want to go back to later.