Homer Christensen

learning + content

This site showcases instructional design, technical writing, content creation, and design.  R. N. Homer Christensen, is an award-winning writer and instructional designer, specializing in content that informs, whether that be structured or informal learning, online help or documentation, live or recorded.

Trip Report: Write the Docs North America


This is a young conference (this is the 2nd year) that is focused entirely on the documentation of software. As such, the talks were fairly focused and largely applicable to many of my primary documentation and online help development tasks. Several of the major software companies were represented, including Google, Mozilla, and Yahoo, and many young innovative companies and contractors gave the most relevant talks.

Some talks centered around Application Programming Interface (API) authoring, which is not part of my core skillset.

Interestingly, several talks were given by software coders/programmers who advocated having the docs written by the coders by exporting fields in their code or read-me file.  This applied mainly to API authoring where the audience is fellow coders.

One of the interesting suggestions that I’d like to explore is creating documentation as ePub files.   I think especially an advanced iBook (where you can embed videos, etc.) might be powerful for users.  It can combine documentation with informal learning strategies and be viewable on multiple devices.

Summary (from the Write The Docs website):

Write the Docs is a two-day conference focused on documentation systems, tech writing theory, and information delivery.

Writing and maintaining documentation involves the talents of a multidisciplinary community of technical writers, designers, typesetters, developers, support teams, marketers, and many others.

This conference creates a time and a place for this community of documentarians to share information, discuss ideas, and work together to improve the art and science of documentation.

We invite all those who write the docs to spread the word:
Docs or it didn't happen!

Useful links:

Main website: http://conf.writethedocs.org/na/2014/index.html

List of presentations and speakers: http://docs.writethedocs.org/2014/na/talks/

Videos of presentations: http://videos.writethedocs.org/category/2/na-2014

Favorite Talks

Some of my favorite talks were:

Christina Elmore - Death by Documentation

The urge to document is at the root of many bad presentation habits.

Despite a renaissance in the art of presentation - think TED Talks, Nancy Duarte, Prezi, and Ignite – we still experience more bad presentations than any lifetime deserves. Even with compelling content and conquered nerves, a presenter’s visual materials can totally tank a talk. And documentation is often to blame.

The real culprit is a conflation of documentation and presentation. Many slide collections end up being an awkward mash-up of the two, and documents suffer when we force them into the mental model of a presentation. (NASA and the military offer striking examples of these failures.) Why have the differences between documentation and presentation been lost? How can we make better sense of these two forms to create more engaging presentations and better documents?

What I liked About It

I learned much about presenting here.  I don’t know why I didn’t put it together before. So this was more of personal awakening where I could see the opportunities I missed during my presentation, and many ways to improve for my next.

Christopher Kelleher - Make Music Not Noise

Can the values of music guide us to create better documentation? We’ll look at examples of noisy documentation and consider how we can use the noise vs. music distinction to improve the world by documenting it better.

sound without structure = noise
sound + satisfying structure = music
information + satisfying structure = successful documentation

First we’ll examine cases of intentional noise – documents that are designed to be hard to follow. Think convoluted cable bills or droning usage agreements. This is noise with a purpose: if we give up on following along, the document has done its job because the original goal was to make us surrender, not understand. We’ll talk about how to isolate the noise and demand higher standards.

And then there are documents that mean well but perform badly — the audience can discern a melody, but it’s either buried or gratingly inconsistent. Examples include tediously detailed consent forms, haphazard project documents, or reports that drift through random facts and jargon. This is the dissonance of badly structured information — making sound without making sense. Applying a musicality standard can guide authors out of the muck.

What I liked About It

Entertaining presentation that delighted as it progressed.  Documentation designed to obfuscate (like a license agreement) contrasted with those designed to communicate/teach.

Mo Nishiyama - Did It In Minutes: The Art of Documenting Meeting Notes

If elegant technical help pages are the shiny, sleek roadsters of the documentation world, the plebeian meeting minutes are the dump trucks. Despite being regarded as an unglamorous business tool, minutes serve an important function for communicating effectively with colleagues.

Meeting minutes document changes to business operations, chronicle the decisions that were made, capture the essential gist of discussions, and serve as handy references for those colleagues who were unable to attend the meeting–or for those who indulged in siestas during the gathering. Minutes can even justify whether a meeting was necessary in the first place.

Effective minutes can save companies labor costs: well-written meeting notes can prevent both meeting organizers and absent team members valuable time that would otherwise be spent trying to bring absentees up to speed. Accurate meeting notes can clearly define policies and expectations in a workgroup.

In this presentation, we will discuss best practices for documenting and curating meeting notes. Using meeting templates, de-mystifying technical jargons, breaking free of the chronological reporting, adhering to the WTF (Write The Facts) approach, carving time for editing notes, charting follow-up tasks, and judiciously spicing up otherwise-mundane topics are examples of these best practices. Special emphasis will be placed on writing with clarity and empathy in mind for team members, whether they were present at the meeting or not.

What I liked About It

Very funny delivery. Some good ideas, not only for note-taking, but for documentation as well.

Matthew Lyon - Minimum Viable Documentation

You’re working at a startup building a “minimum viable product” – and everything about the product is being cut down to bare minimum to reduce the risk and cost of failure. Deciding what to include in “Minimum Viable” is difficult, and the value of documentation in service of product development is often misunderstood by project managers who work in this style, who often choose to forgo documentation altogether.

I will make the case for including documentation in “viable”: We’ll consider ways of understanding your target audience, helping introduce them to your software and getting them unstuck, and make the case for minimum-viable in-house developer documentation.

What I liked About It

I’d never really thought about the concept of “minimum viable documentation:” doing the minimum necessary to accomplish the task. While on the surface it sounds like laziness, it is really just writing exactly what needs to be there and nothing else.  In that regard, it’s focused and efficient.

Mark Tattersall - Documentation as Product¶

“Write the Docs” is so often a line item found at the end of a project plan. But documentation deserves so much more attention and thought as good documentation does more than just describe how to use or implement a new feature, particularly in the case of API documentation. It is both the shop window and instruction manual. The tone of the documentation represents your product, and the complexity, simplicity or ‘magic’ needs to shine through.

My talk will focus on two objectives:

  • Why does Documentation deserve product planning on its own?
  • What do you mean Documentation as a Product?

What I liked About It

Documentation as marketing.  People turn off when being actively marketed to, and Documentation is a great bridge. The first “enduring interaction your users have” with your product.

Copyright © 2014 by R. N. Homer Christensen and nForming.  All rights reserved.