Open Advice/Documentation and My Former Self

Documentation and My Former Self

by Anne Gentle

in: Open Advice

This text is available under the CC-BY-SA license. (see also: Open Advice/Info)

Contents 1 about the author

An intriguing premise – spill my guts about what I wish I knew about open source and documentation. Rather than tell you what I wish you knew about open source and documentation, I must tell you what I wish my former self knew. The request evokes a sense of regret or remorse or even horrified notions of “What was I thinking?”

In my case, my former self was just five years younger than now, a thirty-something established professional. In contrast, others may recall their first experiences with open source as a teenager. Jono Bacon in his book, Art of Community, recounts standing in front of an apartment door with his heart pounding, about to meet someone he had only talked to online through an open source community. I have experienced that first in-person meeting with people I have only met online, but my first serious foray into the world of open source documentation came when I responded to an emailed request for help. The email was from a former coworker, asking for documentation help on the XO laptop, the charter project for One Laptop Per Child. I pondered the perceived opportunity, talking to my friends and spouse, wondering if it would be a good chance to experiment with new doc techniques and try something I had never done before, wiki-based documentation. Since that first experimentation, I have joined OpenStack, an open source project for cloud computing software, working full time on community documentation and support efforts.

I immediately think of the many contradictions I have found along the way. I have uncovered surprising points and counterpoints for each observation. For example, documentation absolutely matters for support, education, adoption, yet, an open source community will march on despite a lack of documentation or completely flawed docs. Another seeming juxtaposition of values is that documentation should be a good onboarding task, a starting point for new volunteers, yet new community members know so little that they can not possibly write or even edit effectively, nor are newbies familiar with the various audiences served by doc. Word on the street lately is that “developers should write developer docs” because they know the audience well and can serve others like themselves best. In my experience, new, fresh eyes are welcome to the project and some people are able to write down and share with others those fresh, empathetic eyes. You do not want to create a “newbies-only” culture around docs, though, because it is important that the key technical community members support doc efforts with their contributions and encourage others to do so.

A bit of a dirty little secret for documentation related to open source projects is that the lines drawn between official docs and unofficial doc projects are blurred at best. I wish I had known that documentation efforts get forked all the time, and new web sites can sprout up where there were none. Sprawling docs do not offer the most efficient way for people to learn about the project or software, but a meandering walk through a large set of web documentation might be more telling to those who want to read between the lines and interpret what is going on in the community through the documentation. Lots of forking and multiple audiences served may mean that the product is complex and serves many. It also can mean that no strong core documentation ethos exists in the community, so unorchestrated efforts are the norm.

I wish when I started that I had some ability to gather the “social weather” of an online community. When you walk into a restaurant with white tablecloths and couples dining and a low-level volume of conversations, the visual and auditory information you receive sets the ambiance and gives you certain clues about what to expect from your dining experience. You can translate this concept of social weather to online communities as well. An open source community gives certain clues in their mailing lists, for example. A list landing page prefixed with a lot of rules and policy around posting will be heavy in governance. A mailing list that has multiple posts emphasizing that “there are no dumb questions” is more approachable for new doc writers. I also wish I knew of a way to not only do a content audit – a listing of the content available for the open source project – but also to do a community audit – a listing of the influential members in the open source community, be they contributors or otherwise.

Lastly, an observation about open source and doc that I have enjoyed validating is the concept that documentation can occur in “sprints” – in short bursts of energy with a focused audience and outline and resulting in a known set of documentation. I was so happy to hear at a talk at SXSW Interactive that sprints are perfectly acceptable for online collaboration and you could expect lags in energy level, and that is okay. Software documentation is often fast and furious in the winding-down-days of a release cycle, and that is acceptable in open source, community-based documentation. You can be strategic and coordinated and still offer a high-energy event around documentation. These are exciting times in open source, and my former self felt it! It is a good thing you can keep learning and growing your former self into your current self with the collection of advice to tote along with you.

about the author

Anne Gentle is the fanatical technical writer and community documentation coordinator at Rackspace for OpenStack, an open source cloud computing project. Prior to joining OpenStack, Anne worked as a community publishing consultant, providing strategic direction for professional writers who want to produce online content with wikis with user-generated pages and comments. Her enthusiasm for community methods for documentation prompted her to write a book about using social publishing techniques for technical documentation titled Conversation and Community: The Social Web for Documentation. She also volunteers as a documentation maintainer for FLOSS Manuals, which provides open source documentation for open source projects.