Writing tech docs

like a hacker with Jekyll

Created by Tom Johnson

The scenario

Tool options

Static site generators

Jekyll

"Blogging like a hacker"

"On Sunday, October 19th, I sat down in my San Francisco apartment with a glass of apple cider and a clear mind. After a period of reflection, I had an idea. While I'm not specifically trained as an author of prose, I am trained as an author of code. What would happen if I approached blogging from a software development perspective? What would that look like?"
Blogging like a hacker, Tom Preston-Werner, co-founder of Github
What would happen if we approached technical writing from a software development perspective?

CMS vs. Static site generators

Jekyll how-to

Why people like Jekyll:

  • Simple
  • Stable
  • Secure
  • Lightweight
  • Fast
More details »

Doc sites using Jekyll

More details »

Writing tech docs like a hacker

Site generator: Jekyll
File format: Text files
Authoring: Text editor
Advanced logic: Liquid
Collaboration: Git
Versioning: Git
Building: Server hooks

Using Jekyll for tech writing: My journey

Designing the Site?

Solution: Bootstrap

  • Turns out theming is easy
  • Easy to clone any existing site
  • Use Bootstrap for framework
More details »

Content re-use?

Solution: Includes

Store content in _includes folder. Then insert like this:


{% include myfile.html %}

Conditional filtering?

Solution: Liquid


{% if site.audience == "administrators" %}
show this to administrators
{% elsif site.audience == "analysts" %}
show this to analysts
{% endif %}
More details »

Multiple outputs?

Solution: Multiple config files

  • Separate config files for each variant
  • Each config file has various properties
    (audience, platform, product, version)
  • Create scripts that compile build commands

Sample build command:


//build administrators output
jekyll build --config config_administrators.yml --destination ../outputs/admins

//build analysts output
jekyll build --config config_analysts.yml --destination ../outputs/analysts
More details »

Multi-level navigation menu?

Solution: Separate data from presentation

  • Store menu items in YAML file
  • "for" loop in HTML layout parses through YAML
  • Navgoco jQuery component handles other aspects (expand/collapse, cookie, accordion)
More details »

Alerts: Notes, tips, cautions?

Solution: Includes with Parameters

  • Store note code as include
  • Pass parameters with include code

// create the note.html include:

Note: {{include.content}}
//use it like this: {% include note.html content="My note content goes here ..." %}
More details »

Avoiding broken links?

Solution: YAML-based links

  • Iterate through TOC to create YAML file to get link names
  • Store urls.yml in _data folder
  • Reference links like this: {{site.data.urls.myfile.link}}
More details »

PDF output?

Solution: Prince XML

  • Iterate through sidebar menu to get list of links
  • Feed the list of links to Prince XML
  • Store command in shell script
More details »

Re-use across projects?

Solution: Single project for writers

  • All writers work in same project
  • Collaborate through version control
  • Each project stored in its own subfolder
  • Exclude other directories in each project's config file
More details »

Version control workflows?

Solution: Learn the needed workflow

  • Focus only on necessary Git commands
  • Coordinate more among team members
  • Avoid simultaneously editing the same page
  • Look regularly at commit logs

Simplicity?

Solution: Stick with Core Jekyll

  • Avoid plugins or overly complicated code
  • Have all writers work in same project
  • Stop changing processes/code each month
  • Establish standards and provide training

Search?

Solution: Swiftype or Algolia

  • Implementation requires UX skills
  • More difficult if content isn't public

Translation?

Solution: Separate projects

  • Separate out UI strings into data file
  • Send out Markdown files for translation
  • Create new project with translated files

How Jekyll makes me feel

Analogy with first telephone

Bell and an early model of the telephone
More details »

Disruptive innovations

Social coding

Documentation theme
for Jekyll

  • Newer theme: Single output, multiple sidebars (Github repo)
  • Older theme: Multiple outputs, one sidebar (Github repo)

THE END

Tom Johnson
@tomjohnson
idratherbewriting.com