Presentation storming - graphitefriction/oscon-2013-docs-workshop GitHub Wiki

Bad examples

• inc.com

• github.com

Good examples

• asciidoctor.org

• github.com (as of 2013/07/15)

• tuning the output/presentation (enable toc, syntax highlighting, etc)

• DRY

• set context (e.g., imagesdir)

• motivation / call to action

• target audience / relate to them

• logistics

• title & abstract

• prerequisites

• list of techs & concepts

• reading material

• discount code

• reusable content

• reduce friction for creating content

• the "S" in CMS = git (VCS) + AsciiDoc (format) + Awestruct (publisher)

• separation of responsibility - each tool has a specific focus, can be swapped out

• tech proof

• maintainability

• preserve asset

• less fragile

• localize changes to system

Producers should get content back in a format they recognize as their own. Otherwise, you put up a barrier to their continued participation.

Examples of formats that violate this principle:

• DocBook

• PDF

• "In-Design" ML

Layout needs to be automated and predictable, and only used at the very end of production.

Raises question of how one format is transformed to another (e.g., AsciiDoc → HTML). The conversion should be automated and predictable.

Resorting to HTML undermines the whole system / objective.

• reusable content (COPE); well-structured, reusable content

• focused, targeted, clear goals (shapes and sizes of content)

• accessibility

  • readability (typography & contrast)

  • "mobile first"

  • approachability of content for readers and creators (balanced system)

• automation

• human-readable semantics (chunked, structured content)

• versioning & collaboration

• DRY

• workflow

git + AsciiDoc + Awestruct are a realization of these principles. They can still stand to be improved. The principles / concepts can be applied to other systems (e.g., Drupal).