Beyond MAN Pages

3 Things to Make your Open Source Project a User Favourite

Beth Agnew

FSOSS 2011

Overview

My brief bio Involve users throughout life cycle

–Documentation–Usability–Publicity

Technical communication help Delivering a superb user experience

Bio

Seneca Tech Comm – Co-ordinator

Veteran TechwriterBlogger, Vlogger

Gamer

www.senecatechcomm.com

A Reminder…

Project Life Cycle1. Planning2. Design3. Development4. Implementation5. Maintenance

Involve user community (or a representative user) at every stage

Requirements & Planning

Specifications & Design

Construction / Code / Development

Testing

Implementation

Maintenance

Project Life Cycle

Design and Plan Develop (Write) Review & Edit Publish and Maintain

Documentation

Stock photo

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!

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

Usability

Stock photo

User Focus

Who is the audience?

–End users–Other developers–Multiple audiences–Combination audiences–5W1H (who, what, when, where, why, how)

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?

Publicity

Stock photo

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

Shameless Plug

By Mike O’Dowd

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

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

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

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

By Paul Henman

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

#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

Questions?