Asciidoctor Coder Writes Less Documentation

Nicole C. EngardI've been working as the documentation manager for the Koha project for six and a half years, so when I saw that Sarah White would be talking about documentation at OSCON this year I knew I wanted a chance to interview her.

Sarah will be giving a talk entitled Writing Documentation that Satisfies Your Users. Sarah believes in helping users succeed at solving their problems by working on and helping others write documentation for open source software, and I have to agree with her that one of the best parts of working on an open source project (not just writing the documentation) is getting to meet awesome people!

Learn more about Sarah in my interview with her. And, make sure you stop in to meet her at OSCON 2014 if you're there.

Q: How did you get involved in open source?

White: I discovered open source software when I was in college and working with ginormous CSV tables and satellite images. My classes and job required collaboration between academic institutions and government agencies and finding ways to integrate data from lots of sources. Open source projects were absolutely integral to injecting the data into proprietary programs and extending those programs' capabilities. For me, open source has always provided customizable and flexible solutions. Since getting involved in open source over 15 years ago, I've never encountered enough compelling reasons to switch from a Linux OS or open source tools.

Q: Why did you start OpenDevise?

White: I started OpenDevise with Dan Allen to help open source projects communicate clearly and effectively with their user and development communities.

Q: Have you written (or assisted in writing) documentation for any open source projects?

White: I'm currently working on the documentation for the Asciidoctor project, and I've written educational content for Arquillian and Fedora.

Q: What have you learned working on open source documentation projects?

White: Documenting open source projects is time consuming. It's also fun and invigorating. When you're creating documentation for a project you get the pole position at the intersection between a project's maintainers and users. You're helping users succeed at solving their problems while collaborating with developers to improve the usability of the project. And the best part of writing documentation is that I get to meet lots of awesome people.

Q: What are your favorite open source tools?

White: Fedora, it's clean, modern, fast, and just works no matter what external devices I throw at it. Arquillian, because accurate testing is a must, and the community is one of the greatest. Open source. Communities. Ever. Git, without version control I'd be locked in a little padded cell. Blender and darktable, they make my life beautiful and are uber powerful. And last, but certainly not least, are my two favorite writing tools, gedit and Asciidoctor.

Q: How did the Asciidoctor project come about?

White: In 2012, developers at GitHub began a Ruby implementation of AsciiDoc and open sourced the project. Matthew McCullough had recommended AsciiDoc to Dan and I earlier that year when we were evaluating markup languages that played well with GitHub, GitHub Pages, and Ruby-based static website generators. Dan and I helped finish the first compliant version of Asciidoctor (0.1.0) in early 2013, and Ryan Waldron handed the project over to us. Since then, the Asciidoctor community has rapidly advanced and improved the software's capabilities. The Asciidoctor Project now encompasses more than 30 repositories—you can output PDFs and slidedecks, view your content live, in-browser, with the JavaScript implementation, and integrate with Gradle and Maven. Note: AsciiDoc.py was created by Stuart Rackham.

Q: When an open source project is lacking in documentation, where does one start? How does one not only write the documentation, but get the community to support and participate in their efforts?

White: When a project doesn't have documentation, I get together with the project maintainers and find out what their vision and goals are for the project. At the same time, I talk to the project's users and learn about the project from their perspective. What are they using the project for? Where and how are they using it? How does it help them? What problems have they encountered while using (or trying to use) the project?

Additionally, I collect and analyze all the content I can find about the project such as blog posts, presentations, screencasts, etc. I also dig through the issue tracker, mailing list, discussion list, social media mentions and any analytics I can get my hands on. Finally, I walk through the code and try to use the project without any assistance. What's the point of gathering all this information? To determine the current and acute pains of the users. I use those pain points as a way to focus the initial documentation, like README files and tutorials, so it answers the most common needs and questions of the users.

Q: Is there a method you find that works best for documenting software? Groups working simultaneously, an individual documentation author, some combination of the above?

White: I haven't found a silver bullet workflow for documenting software because every project and its ecosystem is unique. But I do know how to spark the process. You've got to get information about the software flowing from the project maintainers and core contributors. They are an untapped mine of information, but that information tends to get stuck in their heads. A tactic I used for one successful project was to ask the maintainers and developers to tell me one reason they loved their software.

I discovered a plethora of essential benefits and features to document. And a lot of that documentation now existed in the form of email replies. I just had to structure it. This brings to mind one of my favorite quotes on the subject.

Most people are OK with writing e-mails. They don't consider this writing. There's no writer’s block. Someone asks you a question, you reply and type away.—Stoyan Stefanov

Which leads me to another key part of the process: make the contribution workflow as basic as possible. Throw out as many rules, requirements, and tools as you can. Nobody likes rules anyway. And they're just one more thing that has to be written, edited, and maintained. I don't know about you, but I'd rather spend my time writing code snippets that chronicle the adventures of wolpertingers, aliens, and lost defensive operations manuals.