*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.
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.
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.
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.
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.
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.
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”.
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.
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)
(IMHO)