Easier Documentation, Simpler Websites And Faster Collaboration @ OSCON 2013

by Dan Allen -

Do you find producing and collaborating on documentation or web content difficult? At OSCON 2013, we’ll work with you to reduce the friction of creating content by simplifying your content workflow, teaching you how to collaborate more efficiently and helping to make writing and publishing enjoyable!

OSCON banner

Join us on Tuesday, July 23 at our workshop titled Easier Documentation, Simpler Websites And Faster Collaboration to learn about tools and techniques that lighten your documentation workload and jumpstart your content strategy. To attend, register for OSCON 2013, then sign up for the workshop!

TIP: Use code ARQIKE for a 20% discount off registration!

How?

It begins with writing content…​

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

Plain text *embellished* with _subtle_ markup.

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!

Zurb Foundation Yeti

Next, we do some baking.

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.

It’s push to publish!

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.

Revision history in GitHub
The revision history is safely tucked away in the git repository.

Don’t forget to chunk!

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.

Chunking 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.

Recap

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:

  • lightweight markup makes writing documentation easier

  • static site generators and CSS frameworks make websites simpler

  • git and GitHub make collaborating on content and publishing it online faster

…​all powered by open source software:

Ruby

Git

AsciiDoc / Asciidoctor

Awestruct

Jekyll

Haml / Slim

SASS / Compass

Zurb Foundation

Travis CI

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

What, Where and When?

Title:

Easier Documentation, Simpler Websites And Faster Collaboration
Date:

Tuesday, July 23, 2013
Time:

1:30 - 5:00 PM (3h 30m)
Room:

D139/140, Oregon Convention Center
Type:

Workshop
Category:

Tools & Techniques

You can find all the details about the workshop, including the session abstract, on the official session page.

Who?

Attendees

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?

  • manuals, user guides, tutorials or READMEs

  • news, press releases or announcements

  • articles or books

  • brochures or press kits

  • conference or event information

  • request for proposals (RFPs)

  • resume or personal site

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

Trainers

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 at Red Hat, he leads the Asciidoctor project and serves as the community manager for Arquillian. He draws on these experiences to help make a variety of open source projects wildly successful. Besides drinking a Trappist beer or indulging in Belgian chocolate, there’s nothing he’d rather do.

Sarah White Sarah White

Sarah is the content strategist for both the Arquillian and Asciidoctor projects—​an ideal position for someone passionate about open source, alien invasions and writing.

If there’s room for improvement, Sarah will find it. Lots of it.

Long ago, in a not-too-distant galaxy, she assessed hazardous waste sites and tracked pesticide routes through watersheds. So she knows a thing or two about identifying and eradicating stuff that kills, including software bugs and poor documentation.

Prerequisites

Knowledge of HTML and being comfortable using the commandline are both essential. Some knowledge of git and Ruby is useful, though a novice should be able to pick up the necessary training “on the job”.

Reading list

We’ve prepared some reading material that will give you a better idea of what the session is about and what you’ll be learning. These resources should also help you continue to learn about the subject after the workshop is over.

Strategy
Tech

A full list of resources is available on the Reference Resources page on the workshop’s wiki.

We look forward to seeing you at OSCON!

  • 1 of 1