2014 Open Help Conference & Sprints

[michael]

*This topic exists to describe and document the Open Help 2014 conference which I attended. *

NOTE: I attended this event last year along with @paul and @burke. If you are interested in participating, check out the information below and their web site, and indicate your interest here so we can determine who from OpenMRS might go. - MD

The 2014 Open Help Conference & Sprints takes place June 14-18 in downtown Cincinnati, Ohio, USA. Open Help brings together leaders in open source documentation and support, as well as people from across the technical communications industry who are interested in community-based help.

The Open Help Conference features two days of presentations and open discussions. In true open source spirit, our discussions and agenda are led by our attendees, allowing you to learn and share what matters to you most. With some of the most interesting people in the industry, the Open Help Conference showcases the ideas that are shaping the future of help.

Following the conference, multiple teams take part in the Open Help Sprints, collaborative team meetings where people put ideas to work. Don’t have a team to bring to the sprint? Join anyway and learn from the people who are pioneering documentation sprints.

Details: http://openhelpconference.com/

[michael]

TALK: "Help people so they can help you" by Eric Shepherd from Mozilla:

1. Step One: Find and recruit new contributors
   1. Look within your existing project community:
      1. Look for people already contributing in other areas of the project
      2. Relatively "easy" to recruit to help write docs
      3. They likely have knowledge that need to be captured
      4. People "in the know" can cut down on research time
   2. New contributors....
      1. These take more work to find.
      2. Usually, but sometimes they just show up on their own
      3. Usually you have to find them yourself
      4. Look for opportunities!
2. Step Two: Encourage people to contribute
   1. Lower the barrier to entry
      1. Consider whether to allow anonymous contributions
      2. Streamline the registration and login process
      3. Provide a "getting started" guide
      4. Start them off with quick tasts
   2. Add a personal touch
      1. Send a welcome abord email
      2. Offer one on one help, and or a public channel for help
      3. Don't let newcomers get frustrated and quit because they get stuck.
      4. A human face can help boost a contributor's confidence.
   3. Make it worthwhile
      1. Have fun together!
      2. Making the world a better place (really!)
      3. Helping others makes people happier
      4. It just might help your career
3. Step Three: Make contributing easy
   1. Have clearly-defined tasks
      1. Suggest tasks by average expected time to complete, topic area, etc.
      2. Provide options for people with different strengths: Writing, organizing, building samples, creating image assets, etc.
      3. The more options you provide, the easier it is to match contributors to tasks.
      4. Be sure it's clear what's expected for each task.
   2. Have great "meta-documentation"
      1. Documentation about how to contribute
      2. Explain the provided tools
      3. Style, terminology, and localization guides
      4. How to contact SME's and other key contributors
      5. Sample and/or template pages
   3. Provide great tools
      1. Make toolks convenient and comfortable
      2. Guide contributors toward writing in keeping with your style guidelines
      3. Provide appropriate status and task dashboards
      4. Offer easy-to-understand lists of things that need to be done
      5. (Mozilla created their own wiki platform because nothing else fit their requirements.)
4. Step Four: Keep them coming back
   1. Plant the seeds
      1. Real-time community conversations (IRC, etc.)
      2. Mailing lists or forums
      3. Collaboration features in the docs platform (e.g. in-line annotation)
      4. Hold community events and meet-ups
   2. Take care of your community
      1. Give credit where it's due, freely and often (Twitter)
      2. Offer gentle assistance when they make mistakes
      3. Engage community members on a personal level
      4. Offer rewards for good work
      5. Celebrate accomplishments
      6. Remember, these are volunteers!
   3. Watch it grow.
      1. Look at number of users contributing each month
      2. Track documentation status, e.g., http://arewedocumentedyet.com/
      3. Meta-documentation example: https://developer.mozilla.org/en-US/docs/MDN/

[michael]

TALK: "RTFM? Write a better FM!" by Rich Bowen from RedHat

See slides at: http://tm3.org/betterfm

Additional comments & thoughts:

• How many steps is one's first contribution? Is it too painful?
• How quickly can someone feel "worthy" to make a contribution?
• Make sure someone is good at tracking expertise and can connect people with questions to people with answers.
• If you don't know the audience, documentation won't do it's job, and you'll likely speak in the wrong voice.
• Plan for different cultures & different first languages.
• Find out where your audience is discussing your project, go there, help them, and encourage them to come back to the authoritative source.
• "We may know what they need to know, but only they can tell us what they need to know." - Anne Gentle
• "HOWTO" documents can be good, but they may be too specific to the a writer's problem. Often need to curate and make them more generic. Enterprise-type software gets a lot of this because there's no single process for installation & configuration.
• Larry Wall's 3 virtues of a programmer: "Laziness, impatience, and hubris." This doesn't mean you have a license to be a jerk! Wall's 3 virtues of a human being: Diligence, patience, and humility. (These are the necessary ones in an open source project!)
• Important: Answer the question thoroughly, once. Only. Save your answer. Next time, give them a URL.
• Documentation needs both initial and periodic editorial and technical review.
• Never use words or phrases that imply any step (included or not) is trivial. The reader is there because something isn't.
• Are FAQ's frequent because documentation isn't good enough, or because people need to find it in the existing documentation?
• Monthly newsletter should list by name everyone who made their first contribution.
• Contributors to OpenStack get free admission to the user conference.
• Be quick as possible to offer full commit rights.

[michael]

Additional notes from informal Saturday AM conversations:

• For GNOME's 6-month release cycle, they do a doc sprint immediately after a feature freeze (maybe 5 months?), which gives enough time before the release for documentation updates.
• Mozilla: Maybe aim to do documentation at beta release, where features are "more or less" locked down.
• Tweet new documentation and contributors as recognition.

[michael]

TALK: "Community Lessons From IRL" by Shaun McCance

• Shaun has been building open source projects for 10 years, and now he's helping to open a grocery store.
• Neighbors started complaining that there was no grocery store in the neighborhood any more. Someone organized a meeting and they decided to start a grocery co-op.
• They're now figuring out how to grow their project, fundraising, etc. ... all with volunteers.
• Similiar in many ways to FOSS projects, but face to face!

Some lessons learned:

• "Somebody should do something" ... isn't doing something.
• The 90-9-1 Principle still applies. 90% lurkers, 9% contributors, 1% creators.
• Getting the word out is hard.
• Go to where the people are.
• Coordinating volunteers is hard in real life, too. People have busy lives. Hard to do things at the same time.
• Everybody has ideas. Some ideas are good. Some ideas are terrible. It's not always obvious which is which. Some ideas are good but a distraction!
• "Normal" people don't understand our typical FOSS tools.
• There are personal conflicts in real life, too. And they're worse because you see them in person every day!
• There's still burnout in real life, too. And it's worse because you're around the project every day!
• There are still "trolls" in real life, too. But they're not worse because it's not anonymous.
• "Thank you" is a surprisingly powerful motivator.

[michael]

Additional notes from informal Saturday PM conversations.

Content:

• Your "keywords" about content may not match up with those that a reader is using or thinking about.
• If you analyze how people are asking the question, you can take that data to improve your documentation.
• Important to ensure people are classifying/tagging documentation. Much of this is a manual process and can't be automated.

Tools:

• Need for visualizations to show documentation contributions. Shaun has a project (Blip) for this that he'll demonstrate Sunday.
• Dream tool: Match documentation needs with contributors' skills/interests ... automatically.
• Kuma is a pretty nice too for FOSS project documentation but it's not generic (like Zamboni). Catch-22: should other projects help to get there?
• Lots of advantages to and momentum behind things like Markdown, Asciidoc, etc. Allowing people to document via GitHub lets them show their contributions as a "CV" just like developers.

Organizational issues:

• It's possible to do GSoC projects related to documentation if the student is working on improvement the documentation tools and process.
• Most technical writing courses or curricula don't prepare students for technical writing that's needed in open source projects. Some exceptions seem to be Seneca College & Oregon State University.
• When recruiting people for documentation roles, do you want a writer or a technical person?
• It may be difficult to recruit someone documentation roles that sticks around, unless they have a real passion for documentation.
• Different social dynamic in FOSS projects than many "typical" documentation environments.
• Critical to provide regular mentorship for new volunteers (or interns). Provide a list of them small tasks and keep that list curated.
• The top N contributors vary based on topic. People have areas of expertise/preference.
• Having writers (or any users) active in creating/building tools is a great value.
• Something that worked: Get a developer "assigned" to working on developer documentation for a length of time to get a base built up and for that person to get excited about it. That person can share the excitement with others and get others to contribute.
• Paid documentation roles might be best to work on the drudgery stuff that no one would really ever want to pick up.
• Books with good content on onboarding people, particularly into documentation roles: Conversation & Community by Anne Gentle, Art of Community by Jono Bacon, and Building Successful Online Communities: Evidence-Based Social Design by Robert E. Kraut et al.
• It's a big investment to train a volunteer into a leadership position. And it's a big risk. But documentation volunteers may have higher retention rates than engineering ones. Tips: Get them integrated with community, work in public, give responsibility.

Global & cultural issues:

• Many communities exist but are "disconnected" from a project's global community.
• You've got to rotate synchronous meetings by time zone to maximize participation.
• When you make decisions at in-person or private meetings, always summarize and send to mailing lists and solicit feedback.
• Newcomers might not understand IRC culture (e.g. delayed response). It might not be the best place for them. Use notices, topics, etc. to (try to) help people understand.
• Never get into thumb wars with other FOSS projects.

[michael]

TALK: "(Documentation) Outreach in GNOME" by Ekaterina Gerasimova & David King

1. GNOME doc team
   1. Established in 1999
   2. Now made up of mostly volunteer contributors, but started as mostly-paid people (Sun)
   3. Valuable contributions from other community members, esp. translators
   4. 10 or so team members
   5. Documentation areas
      1. User help: http://help.gnome.org/user/
      2. System admin guide: http://help.gnome.org/admin/
      3. Developer documentation: http://developer.gnome.org/
2. Making a first contribution
   1. Barriers to entry:
      1. Communication: IRC, mailing lists, cultural differences
      2. Infrastructure: Wiki, bug tracker, dvcs (git)
      3. Tools: git (version control), Mallard (language), text editor, yelp (help viewer), yelp-tools (validation and other tools)
      4. Setup: Latest GNOME, jhbuild, virtual machine
      5. Workflow: Varies widely
   2. Tips for newcomers
      1. One of the earliest steps for newcomers is to talk to people!
      2. If possible, get a translation team to follow behind the work of the documentation team.
      3. Some questions may be stupid, but ask anyway! Possible to learn from "stupid" questions just as much.
      4. New volunteers should try to do some mentored work in different areas of documentation.
   3. GNOME team only maintain documentation against the latest version (not old ones). Not enough person-power.
   4. Expectations: Find a problem - Submit a Patch - Patch accepted, rejected, or fixed up
   5. Reality: Find a problen - check related bugs, trace bug origin, talk to the maintiner, designers, community, ?
   6. Every project has a different process for how to submit patches.
3. Reaching out
   1. Where do contributors come from?
      1. Previously: Downstream & related projects
      2. Now: Internships, translation teams
      3. You can't "make" people follow the processes and use the tools, they need to want to do it themselves.
   2. Opportunities
      1. Paid: Google Summer of Code (GSoC), Outreach Program for Women (OPW), Google Code-In (took a lot of overhead), CSDN Summer of Code?
      2. Other: Training sessions
      3. Did a training session and 0 of them had any previous open source contributions.
      4. Guess whether it's a "drive by" and respond for follow-up/rework accordingly.
      5. Retaining newcomers: Real life gets in the way, internship money runs out. The whole team should be mentors.
      6. Try to get volunteers to work on things they actually use.
      7. What can we do? Be a community, reward good work, help them learn & grow

[michael]

Additional notes from informal Sunday AM conversations:

• One of the biggest challenges is getting new (documentation) volunteers to ask for help in IRC.
• Sometimes people are afraid to ask questions to more senior members because they feel that person is "too important". (Senior project members should proactively communicate with newcomers.)
• Great idea to do in-person doc sprints when interns are new. Builds community and increases long-term engagement.

Growing Activity throughout Asia

• English language skills may be the biggest challenge.
• There's a problem of balance between growing user groups and having resources for those people to "do stuff".

[michael]

Additional notes from informal Sunday PM conversations:

• Universities may often provide venues for free, especially if there is some pressure from local governments. In exchange they might get food service income, housing, etc.
• Mailman 3 (coming soon) will include HyperKitty UI which accomplishes some of the same things as Discourse. Essentially a web forum UI on top of the Mailman app.
• Standardization around "Ask PROJECTNAME" Q&A sites, regardless of tech. Askbot seems to have replaced/abandoned OSQA so there aren't many free alternatives.
• Comments on documentation are hard to maintain (current, out of date, etc.). Refer documentation follow-up questions to Q&A site.
• Bugzilla is coming up with a new release with lots of changes in workflow, UI, etc. Mozilla just passed 1mn issues in Bugzilla!
• PressGang CCMS: An Open Source, API-Driven Documentation Design, Writing, and Illustration Platform - https://pressgang-ccms.github.io/
• Single source of documentation - don't duplicate across systems/resources!
• Kuma still doesn't have much work done in terms of admin. Most work has been on front-end so far. Just standard Django admin panels.
• TODO: Learn about http://standu.ps/

[michael]

Here are some of my own final synthesized learning outcomes from the weekend:

• Documentation is hard for FOSS projects of all sizes!
• Most larger/mature projects seem to have started their documentation efforts with paid team members, who then helped mentor and grow a volunteer community. Eventually, the paid team members might be able to "go away" and a team may be fully volunteer-based. (There are of course exceptions to this scenario!)
• Documentation should be "divided" into three categories: developer resources (training, reference, etc.), user resources (help pages, installation guides, etc.), and meta documentation about the project. User resources should be maintained in version control and updated alongside each new product release. Developer resources and project meta-documentation can be more wiki-style, evolving over time.
• Documentation should go through scheduled editorial (style) and technical (accuracy) reviews.
• Documentation can be used as a way to organize translation volunteers and give them a steady supply of work.
• Everything written earlier in this topic is pretty important. (IMHO)