Sick during a work trip

This is my second work trip where I was put out of commission for at least one day. Jet lag, inadequate sleep, exhaustion, and pushing myself too hard are the likely culprits.

I’m really thankful for my coworkers — especially to my roommate, Paul Ciano, for the DayQuil and NyQuil
— for supporting me while I’m quarantined in my bedroom.

About these ads

April Blogging Challenge

Fellow Automattic colleague, Justin Shreve, challenges us to publish a post on our blog daily for the month of April. On one of our internal sites, I said I’d participate to hold myself accountable.

A few things:

  • I published notes from several speakers at Write The Docs EU the last two days, and ran out of steam near on the second day.
  • I write my ideas in Simplenote with each item tagged “blog”.

While it’s minutes after midnight in Budapest, I’m going by the Pacific Daylight Time since I live in the Los Angeles area. I’m two for two this month. Yay!

Interested? Possibly intrigued? Read his post for more details, join us, and leave a comment. Ignore the date and give it a try for the rest of the month.

You can publish from any site, but we’d also love for you to setup a free blog at I’m proud of our work, and we’re always happy to help. :)

Tip: Need ideas? Check out the free eBook 365 Writing Prompts by The Daily Post at


Write The Docs EU — Fintan Bolton — The community wrote my docs!

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

Is community–written documentation a good idea? Absolutely. As an example, Red Hat had 6,000 pages of documentation — 1,000 were from the community.

Wikis are powerful:

  • Low barrier to contribute.
  • Instant publication and gratification.
  • Zero learning curve (almost).
  • Editable as plain text.

Pros for DocBook/DITA:

  • Good formats for archiving docs.
  • Rich markup vocabulary.
  • Precise and well–defined syntax.
  • Sophisticated build options (e.g. conditions and profiling, includes and con refs, entities)

What’s the impedance mismatch between the community and corporate documentation?

  • Variable quality (e.g. formatting, style).
  • No versioning.
  • Inappropriate content (stuff you wouldn’t want to support, inaccurate claims, spam)

Synchronizing community and product documentation. Rather than tracking community–generated docs and merging with product docs, track community–generated docs from previous community–generated doc changes, then convert the latest iteration into the product docs. Don’t clobber the work of other contributors, lest you lose popularity. Keep in mind that competitors will use comity–written docs.

In conclusion, integrating community–written docs is a big issue, and involves more than a conversion tool. On the flip side, there can be big rewards.

Fintan Bolton is from Red Hat.

Write The Docs EU — Christine Burwinkle — Pairing with designers to create a seamless user experience

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

Christine is a tech writer from Atlassian, who is best known for Jira and Confluence.

  • Went from five to thirty designers in the last two years.
  • Goal: Help casual users, too!
  • Ten tech writers, 400 developers.

Techniques borrowed from designers are used for their writing.

Three main design principles (printed and framed, hanging on their office wall):

  1. Be familiar
  2. Grow with me (help users become power users)
  3. Give me clarity

Aside: Android UX principle is her personal favorite.

Audience/Personas — they printed them everywhere.

Designers took a year–long project:

  1. What role is a feature targeting.
  2. What is assumed skills/background
  3. How do

Leverage data from designers to help them craft better documentation.

Measure success by piggybacking:

  • Usability testing to determine if they need documentation, and publishing FAQs (if necessary).
  • Analytics results.

Diving into borrowing design techniques

Workshopping example: Empathy maps (to bring focus to the user)

  • Better understand their feelings “before and after” a situation
  • Work backwards from the “after” situation to create an ideal state, and empower users.

They’re huge fans of Post–Its:

  • Easy to move ideas around.
  • Excellent for separate collaboration and brainstorming.
  • Inexpensive, mobile, and fun!

Workshopping example: Sparring sessions

  • Critique session to bring group thinking into design and planning.
  • Confirms if goals are met with the prototype.

Sparring with TWs (technical writers)

Before the session, TW sends:

  • Draft to discuss
  • List of goals in the document

Superb sparring session tips

  • Timebox!
  • If your team is given to negativity, try positives–only for five minutes. Fantastic idea!
  • Make sure everyone is heard. Use a checklist, or give everyone one minute to list feedback.
  • Leave with at least three action items.

Workshopping example: 6–ups

  • Divide a sheet into six parts.
  • Focuses on ideal solutions.
  • Gets out of thinking in words. (Draw!)
  • Great method to build on ideas from colleagues.

Workshopping example: User stories

  • How does a user get to a feature? Is it controlled? From many different areas with different goals?
  • What does a user do before? What do they (usually) do next?
  • If they fall out of line in the process, documentation is needed for additional context.
  • Lo–Fi: Use colored stickers to “vote”, then build the document plan based on problem areas.
  • Australian slang: “Doco” is short for documentation. :)

Finding the right projects — look for:

  • A team that finds value in design and tech writing.
  • A designer who sees value in the docs
  • A new project that’s running lean and has some momentum.
  • Look for projects that are data–driven.

Explore and expand

  • Read design principles and techniques.
  • Follow UX blogs.
  • Write a documentation experience plan.

Write The Docs EU — Robert Lehmann — Self-Directed Learning Material

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

Don’t teach dogmatically.

Collaboration can kill cohesion, so choose one champion for the discussion.

Use the right tools and lightweight markup; they use Jekyll and Sphinx.

Begin with the end in mind. For example, when you start to explain a process, if you mention a few things that haven’t been covered before, backtrack and write that information in a new (earlier) chapter.

Encourage experiments so people can appreciate going through the exercise and learning from it. On a related note, “no pain, no gain”.

Being redundant is good, but being concise is better. Find balance between the two.

Translate verbatim and sheepishly. If you spot anything wrong, update the original source first.

How do they teach?

  • Teachers need to remember that “their keyboard is made of lava”. Instruct the students to do it.
  • Use the Socratic method. Don’t give answers. e.g. “Good question! What could you do?”
  • “Feedback is the breakfast of champions.”

For more information, see Coaching Guidelines.

Write The Docs EU — Tom Christie — Designing MkDocs

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

MkDocs is used to create project documentation with Markdown.


  • Needs documentation for open source projects, such as the Django REST framework.
  • Documentation is the design for the product.
  • Built a custom–script to redo the Django REST framework — which was hard–wired to that specific project — and MkDocs was born!

(As an aside, Tom is a fan of the simple aesthetic of the Mou editor, which allows him to visualize the document rather than using a regular editor.

Requires Python and pip, install took about thirty seconds. Has a single configuration file (YAML). Will automatically reload the content after editing any of the source, configuration, or theme files.

  • Use relative links.
  • Documentation will be hyperlinked in the editor.
  • Use references to target a page or title anywhere in the documentation.
  • Name the linked title explicitly (if needed).

Some configuration options:

  • site_name (required)
  • site_url
  • site_description
  • repo_url (like GitHub)
  • copyright
  • google_analytics

Custom themes are available (see the Bootswatch project.)

mkdocs build builds the site to the “site” directory for static site deployment, such as GitHub pages or Amazon S3. (MkDocs already includes GitHub page support.)

Focus of MkDocs:

  • No programmatic API.
  • No embedded documentation.
  • Not a semantic markup tool.
  • Markdown only.

Lastly, the 1.0 release is in progress, and he needs help, so contact him if you’re interested. Very slick! :)

Write The Docs EU — David Hooker — What I have taught developers about writing

David Hooker

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

What makes us write?

  • We’ve created something we’re proud of, and want the world to understand and use it, and make the world better.
  • More common reason: we want some love.

Increase our corridor high–five count

Video clip from The Simpsons, Season 5: “Homer Goes to College” (regarding jocks versus nerds)

“Geeks shall inherit the earth” — and the jocks tremble. :)

Despite the world changing and geeks have money, power, respect, and women (not in that order), what do geeks still lack? Social skills.

New currency is smartness.

Fix my problem vs. Fix my emotions

Best way to get an attachment is to play on their emotions.

“It doesn’t matter if you can tell an engineer wrote it.” (Translation: It doesn’t matter if it’s boring.) BS!

Five movies that all engineers love (from his non–scientific poll):

  • Matrix
  • Matrix Reloaded
  • Inception
  • Blade Runner
  • Star Wars

Why? All written by geeks. All are love stories.

Point: We all love emotional attachment.

How do we get there?

  1. Start with the good sh*t. Example: The Matrix introduction. (What about Star Wars? Bah. No one has the patience anymore.)
  2. Keep it simple. Examples: Football diagrams comparing Brazilian/Spanish goal vs. English goal. Hemingway. For Sale: Baby Shoes, Never Worn. Intrigue in six words.
  3. Write the sh*t people say. Refers to Chicago Manual of Style 5.2. If you get one annual subscription, get the Chicago Manual of Style.
  4. Don’t repeat sh*t.

When we took these four rules to the Prezi engineering blog, it was picked up by The Guardian Blog as one of the engineering blogs you should read.