Materials and related resources for the OSCON 2013 Workshop: Easier Documentation, Simpler Websites And Faster Collaboration
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
images
slides
.gitignore
README.adoc
activate-asciidoc-content.adoc
activate-posts-extension.adoc
add-comments-and-analytics.adoc
add-sidebar-and-collaborate-buttons.adoc
awestruct-asciidoc-tutorial.adoc
chunked-content.adoc
configure-theme-for-asciidoc-and-website.adoc
configure-website-name-title-author-and-organization.adoc
content.adoc
convert-markdown-to-asciidoc.adoc
custom-domain.adoc
deploy-to-github-pages.adoc
extensionless-urls.adoc
install-awestruct.adoc
install-rake-and-bundler.adoc
setting-up-your-workstation.adoc
setup-git-repository-for-project.adoc
setup-new-website-project-with-awestruct.adoc
tutorial-order.adoc
using-images-and-videos.adoc
using-source-code-in-website.adoc

README.adoc

OSCON 2013 Docs Workshop

OSCON 2013 Docs Workshop

The lesson plan and materials for the workshop Easier Documentation, Simpler Websites And Faster Collaboration to be presented at OSCON 2013.

See the announcement on asciidoctor.org.

When and Where

Workshop

Date

Tuesday, July 23, 2013

Time

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

Room

D139/140

Category

Tools & Techniques

More info

General

Conference Dates

July 22-26, 2013

Conference Location

Oregon Convention Center
777 NE Martin Luther King, Jr. Blvd.,
Portland, Oregon 972322

Conference Website

oscon.com

Abstract

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

Tutorial requirements and instructions for attendees

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

  • Ruby 1.9 (or JRuby 1.7)

  • Git client

  • Text editor

Lessons

This workshop is broken down into several Projects, Modules and Tutorials.