Created by Tom Johnson / @tomjohnson
"As to what your journey says, I think it says that all the current models of tech comm development are deeply unsatisfactory in one way or another."
— Mark Baker, Every Page Is Page One
How would you design the perfect help system?
HTML5 • REST APIs • CSS media queries • oAuth • AJAX • instant search • SVG • augmented reality • Internet of Things • big data • social networks • YouTube • Bootstrap • static site generators • jQuery • YouTube • StackOverflow • Github • continuous integration • LESS & Sass • wikis
decentralization • agile • crowdsourcing • gamification • Cluetrain Manifesto (user-to-user communication) • "Everything Is Miscellaneous" • The Long Tail • semantic web • information architecture • content marketing • transparency • simplicity of design • open source • social coding
information typing • minimalism • task-based documentation • topic-oriented documentation • DITA • DocOps • Every Page Is Page One • emotional language • personalization • interactive video • user-generated content • content strategy • single sourcing
"Github, in my humble opinion, is one of the most revolutionary things that has happened to software in 20 years."
— Joe Malin
File format: | Text files |
Authoring: | Text editor |
Building: | Continuous build scripts |
Collaborating: | Source control |
Versioning: | Source control |
Pushing live: | Terminal commands |
Here's the code for this slide:
<section>
<h3>This slidedeck is just HTML5.</h3>
<p>Here's the code for this slide:</p>
<p>Github repo: <a target="_blank"
href="https://github.com/tomjohnson1492/innovation/">https://github.com/tomjohnson1492/innovation/</a></p>
<p><i>So much more satisfying to work in text file formats.</i></p>
</section>
Github: https://github.com/tomjohnson1492/innovation/
So much more satisfying to work in text-file formats.
One person writing from one perspective in one company, especially an outsider to the actual business context of the user, can't possibly cover all the information needs for every user.
{
"entries":
[
{% for page in site.tooltips %}
{
"id" : "{{ page.id }}",
"body": "{{ page.content | strip_newlines | replace: '\', '\\\\' |
replace: '"', '\\"' }}"
} {% unless forloop.last %},{% endunless %}
{% endfor %}
]
}
<task id="task_mhs_zjk_pp">
<title>Printing a page</title>
<taskbody>
<steps>
<stepsection>To print a page:</stepsection>
<step>
<cmd>Go to <menucascade><uicontrol>File</uicontrol>
<uicontrol>Print</uicontrol></menucascade></cmd>
</step>
<step>
<cmd>Click the <uicontrol>Print</uicontrol>
button.</cmd>
</step>
</steps>
</taskbody>
</task>
## Print a page
1. Go to **File > Print**.
2. Click the **Print** button.
<p audience="mac">Your MacBook Pro is going to make you so happy!</p>
<p audience="pc">Thanks for supporting the dying PC industry.</p>
<p>Congratulations on the purchase of your new computer.</p>
{% if site.audience == "mac" %}
Your MacBook Pro is going to make you so happy!
{% elsif site.audience == "pc" %}
Thanks for supporting the dying PC industry.
{% else %}
Congratulations on the purchase of your new computer.
{% endif %}
<topic id="topic_123">
<note type="warning" id="bolt_warning">Don't overtighten the bolts,
as it may cause stripping.</note>
...
<note conref="notes.dita#topic_123/bolt_warning"/>
_includes/bolt_note.md
<b>Warning:</b> Don't overtighten the bolts, as it may cause stripping.
...
{% include bolt_note.md %}
<topichead navtitle="Links">
<topicref href="keyref_links.dita">
<topicref href="inline_links.dita" audience="field_engineers"/>
</topicref>
<topicref href="related_links.dita">
<topicref href="relationship_tables.dita"/>
</topicref>
</topichead>
entries:
- title: Sidebar
subcategories:
- title: Overview
items:
- title: Introduction
url: /introduction/
audience: customer
print: true
- title: Release Notes
url: /release_notes/
audience: customer, fe
print: false
- title: Getting Started
url: /getting_started/
audience: customer, fe
print: true
<task id="task_123">
<title>How to wash dishes</title>
<shortdesc>My short description ...</shortdesc>
<prereq>Before doing the dishes, you will need soap and
gloves.</prereq>
<taskbody>
<context>
<p>This is my context...</p>
</context>
<steps>
<step>
<cmd>This is step one</cmd>
<info>This is a note...</info>
</step>
<step>
<cmd>This is step two...</cmd>
</step>
---
title: My Doc Collection
summary: "My summary here..."
parameters:
- param1:
title: "my param title"
data_type: "boolean"
description: "my param description"
- param2:
title: "my param title"
data_type: "boolean"
description: "my param description"
---
...
{% for parameter in site.doc.parameters %}
{{parameter.title}}
{{parameter.data_type}}
{{parameter.description}}
Set up XSL-FO transform
No easy workflow, but possible via PrinceXML
DITA | Jekyll |
---|---|
Open source | Open source |
Rules-based | Flexible, free |
Vendor heavy | Vendor light |
CMS-oriented | Github-oriented |
XML architecture | Web architecture |
Committee driven | Developer driven |
XML editor | Text editor |
DITA | Jekyll |
---|---|
Large team | Small team |
Lots of PDFs | Web deliverables |
Tech writer contributors | Developer contributors |
Enforced consistency | Flexibility in design |
$$$$ | $ |
Love XML | Love HTML, CSS, JS |
Prefer CMS | Prefer revision control |