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.

A Thought for Today

I subscribe to Anu Garg's A.Word.A.Day list. There's something very satisfying about receiving the gift of a new word each day.  The post gives the meaning, etymology, and usage of the word, which is usually part of a unified grouping each week.  This week, for instance, the words are all borrowed from Spanish. Today's is arroyo.

I have to confess, however, that my favorite part is the thought for the day which concludes each post. The thoughts are quotes from those famous or little-known, but they almost always touch me. I find I spend the most time in contemplation not considering how I might use the word of the day in normal conversation or my writing, but rather feeling the meaning of the quote.

Todays is this:

Since when do we have to agree with people to defend them from injustice?
— Lillian Hellman, playwright (1905-1984)

I find that I often save these quote snippets and review them occasionally.  Some, like the one above, deal with social justice or just being a good citizen of the earth. Others, like these, are more centered around art and craft:

Besides the noble art of getting things done, there is the noble art of leaving things undone. The wisdom of life consists in the elimination of nonessentials.
— Lin Yutang, writer and translator (1895-1976)
If you want a golden rule that will fit everything, this is it: Have nothing in your houses that you do not know to be useful or believe to be beautiful.
— William Morris (1834 – 1896) English craftsman and poet

One of my favorite books is Elbert Hubbard's Scrap Book. I own a couple of copies; an abused hardback printed in 1923 by the Roycrofters, and another (also printed by the Roycrofters) hand bound with ribbon. Hubbard, the founder of the Roycrofters, collected his favorite quotes. What makes this book different than most collections, however, is the length of the quotes (some go on for pages) and the breadth of the selections and authors.

Trip Report: Write the Docs North America

Impressions

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.

Sometimes you find yourself on the edge...

On the edge of the cliff, somewhere outside of Moab, Utah.

Most of the time, we drive towards our goals, however quickly or slowly as traffic permits, in a sure and certain manner. But every now and again, we get off track and end up having to go to the edge to get the lay of the land.

Recently, I had just that experience. I was in a long-term project (5 years is fairly long, I'd say, wouldn't you?) that had stalled on the prime's side. I was a sub to a sub, and being on the training end of the tail, was being wagged and tossed about as the political will of the major players saw fit.

(I know I'm mixing my metaphors. Let's just say that the road was getting a little bumpy due to poor financial planning on the prime's side and the asphalt ended on the sub's side, so I had to push on a dirt track that seemed to wander aimlessly wherever the client willed it.  And at this stage of the project, the new staff who had been brought on only a few months earlier, thought that they weren't doing their job unless they redesigned the whole training approach.)

Seriously... I thought about it. Nah, I can't back that up.

Seriously... I thought about it. Nah, I can't back that up.

At about the way-point of the third re-design, I was in desperate need of a break. Indeed, I needed water, refreshment, and a bit of a rest if I were going to see it through to the end. Or not jump off the cliff. (The thought crossed my mind. Seriously.)

Fortunately, I had just such an opportunity:  the Write the Docs conference.  I had agreed to speak there, and after I had presented (first!) and the stress of preparing for it over, I was able to relax and listen to the other presenters. There were some fabulous talks, all focused on documentation for software, and the ripples of that silky stream of thought washed over me and let me see the way to the end. I could once again envision the big picture and find the track that would take me out of the desert and back towards civilized society.

We received the client's approval two weeks later, and training began last week.

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