Easier Documentation, Simpler Websites And Faster Collaboration

Dan Allen (OpenDevise), Sarah White (Asciidoctor, OpenDevise)
Tools and Techniques
Location: D139/140 Level: Intermediate
Average rating: **...
(2.60, 15 ratings)


To spread our message to broader audiences, we should focus more on documentation and less on e-mail. But producing documentation is hard. In this session, we’ll explore an agile documentation workflow that makes writing documentation easier, publishing it online simpler and collaborating on it faster.

It starts with writing documentation in the same format we use to write e-mail, plain text embellished with subtle markup. That’s the goal of lightweight markup languages such as AsciiDoc and Markdown. Their syntax feels natural and allows us to stay focused on the content. They also make the content easy to read and edit in raw form, yet can still be translated to HTML for presentation.

To pull the documentation together into a cohesive website, we’ll take a similar approach of using lightweight markup geared towards web publishing. We’ll leverage Haml or Slim for HTML, Bootstrap or Foundation for layouts and typography and Sass or Compass for custom styles. These languages have the added benefit of keeping the source DRY.

We’ll then use static site generators like Awestruct and Jekyll to build out a static website from these source files. Both tools provide an aggregate compiler to transform the lightweight markup into web content. They also provide both a development mode for previewing the site locally and a mechanism for publishing the website online.

The website produced may be static, but it doesn’t mean it’s stagnant. With the ever increasing capabilities of browsers, you can shift dynamic behavior to the client and bid farewell to server-side security concerns. It also means you can put more processing power into the authoring pipeline.

Finally, we’ll build and publish the website to GitHub pages using a single command, git push. That’s when the real fun starts. You can easily collaborate on the content using git through the use of pull requests and other collaboration tools on GitHub, the revision history safely tucked away in the git repository.

This documentation workflow makes documentation easier, building websites around it simpler and collaborating on the content and publishing it online faster than ever before. Let’s bake better documentation, together.


* Knowledge of HTML is essential. Some knowledge of git and Ruby is useful, though a novice should be able to pick up the necessary training “on the job”.
* Laptop
* GitHub account: http://github.com
* Ruby 1.9 (or JRuby 1.7)
* Git client
* Text editor

QUESTIONS for the speaker?: Use the “Leave a Comment or Question” section at the bottom to address them.

Photo of Dan Allen

Dan Allen


Dan is an open source advocate, community catalyst, author and speaker. He proudly pursues these passions as a Red Hat employee and community member. In his role as Principal Software Engineer, he serves as the Arquillian community manager and draws on that experience to help make a variety of open source projects wildly successful, including Arquillian, Awestruct, Asciidoctor, JBoss Forge and CDI.

Dan is the author of Seam in Action (Manning, 2008), has written articles for IBM developerWorks, NFJS magazine, Java Tech Journal and JAXenter and is an internationally recognized speaker. He has presented at major software conferences including JavaOne, Devoxx, NFJS, UberConf, RWX, JAX and Jazoon and has been recognized as a JavaOne Rock Star, JBossWorld Top Presenter and JAX Hall of Fame speaker.

After a long conference day, you’ll likely find Dan enjoying chatting about tech and community with fellow community members over a Trappist beer.

Photo of Sarah White

Sarah White

Asciidoctor, OpenDevise

Sarah is a Fedora ambassador focused on making Linux a kick-ass Java development environment.

She’s also the content strategist for the Arquillian Testing Platform —a perfect position for someone passionate about open source, alien invasions, and writing.

Long ago, but sadly, not in a distant galaxy, she assessed hazardous waste sites and tracked pesticide routes through watersheds.


Sponsorship Opportunities

For information on exhibition and sponsorship opportunities at the conference, contact Sharon Cordesse at (707) 827-7065 or scordesse@oreilly.com.

Contact Us

View a complete list of OSCON contacts