Easier Documentation, Simpler Websites And Faster Collaboration @ OSCON 2013

…​in the same format you use to write e-mail.

Indeed, that’s the focus of the lightweight markup language AsciiDoc. The AsciiDoc syntax feels natural and that keeps you focused on the content. Content written in AsciiDoc is easy to read and edit in raw form, which facilitates collaboration. It can also be translated into HTML for presentation, hello web publishing!

After composing some documentation in AsciiDoc, we’ll pull together our content into a cohesive website using the static site generators Awestruct and Jekyll. Then we’ll leverage CSS frameworks like Bootstrap and Zurb Foundation to dress up the content with an elegant look and feel.

We’ll then publish our website to GitHub Pages using a single command, git push.

That’s when the real fun starts. From GitHub, we can collaborate on the content using git and the web-based collaboration tools in the GitHub interface.

There are billions of devices connected to the web. And more are coming. Regardless of how the device market changes over time, the challenge for us remains the same. We need to get our content on all of them.

AsciiDoc is more than just a lightweight markup language. It enables and encourages us to write reusable, structured content.

Reusable content can be mixed and matched with other content to create a composition that suits a device, context or situation. It’s also a way to keep our content DRY (Don’t Repeat Yourself) so we don’t have to update the same content in a dozen places, or even two.

Structured content is meaningful, semantic content that is flagged using metadata. We can do lots of things with a document if we know what’s in it. We can pull out a lead or excerpt. We can hide content when it isn’t needed. We can present a structure and allow the user to drill into what they want to see.

Content no longer lives on a “page”. The future unit of publishing is the “chunk”. These smaller, discrete sources can be tuned to specific platforms or aggregated using automation.

The web is changing. It’s left the desktop. It’s now a road warrior. The way we think about content publishing must adapt. More than ever before, we must separate content from presentation.

Writing documentation is hard. So we don’t do it often enough. And yet, we’re skipping out on the best opportunity to reach and influence our target audience. Let’s do something about it.

Attend Easier Documentation, Simpler Websites And Faster Collaboration to learn how:

…​all powered by open source software:

Let’s bake better documentation, together. Documentation that’s reusable and structured.

Open source community members like you who are passionate about documentation and web publishing.

Not sure if that’s you? Do you contribute to, maintain or organize any of the following?

If you nodded, then you’re one of us :)