Easier Documentation, Simpler Websites, Faster Collaboration

About this Presentation

Do you want people to use your software, service or website? Do you want people to respond to your call to action? Do you want to be heard? Naturally. Do you find producing and collaborating on that content a constant hassle? Don't we all.

The key to creating an effective message and scaling it to a broad audience is writing it down, not in a transient medium like e-mail, but rather as documentation. “Ugh, documentation. Writing documentation is hard and boring!” Think again.

Think about all the e-mail you write? What if creating documentation could be as simple and fluent as e-mail? It can be! Imagine if you could collaborate on it the same way you do with code. I think you see where this is going.

In this workshop, 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 help make writing and publishing enjoyable. You'll learn about tools and techniques that lighten your documentation workload and jump start your content strategy. Let's reboot documentation and get your message to resonate!

It begins with writing content…

…in the same format we use to write e-mail, plain text embellished with subtle markup. That's the focus of lightweight markup languages such as AsciiDoc. AsciiDoc's syntax feels natural, which keeps you focused on the content, and it makes content easy to read and edit in raw form, facilitating collaboration. It can even be translated into HTML (or PDF), hello web publishing!

Next, we do some baking

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

Then, 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.

Don't forget to write for the chunk!

The future unit of publishing is the “chunk”–reusable, structured content–which AsciiDoc encourages us to write. These smaller, discrete sources can be tuned to specific platforms or aggregated using automation. It 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.

Writing for the chunk is how we adapt ourselves to adaptive content, and get our content on to the billions of connected devices.

Just write

Writing documentation is hard. But it doesn't have to be. Come discover how to make documentation easier, building and publishing websites around it simpler and collaborating on the content faster than ever. Let's bake better documentation, together–documentation that's reusable and structured.