The beauty of tech documentation

Documenting WordPress and more

The WordPress® Codex is a “living repository for WordPress information and documentation.” It contains deep documentation on WordPress features, how-tos on working with themes and plugins, as well as learning materials. It does so in 35 languages from around the world. The Codex is also just one of myriad ways that developers, designers and end users can find documentation about WordPress.

Targeted communication

Siobhan McKeown is on the documentation team for WordPress, and has written an extremely rich article on creating documentation. (It’s relevant for other projects, too, but there are some WordPress-specific bits in there.) One key thing in the article is the recognition that documentation needs to meet the needs of the learners who are accessing it. It then goes on to explicitly recognize that, since individuals have unique learning styles, the ways we communicate with them must be unique as well.

“A few years ago, I took a teacher-training course while teaching writing to adults. While I don’t teach much anymore, I still integrate an aspect of learning theory into my process when writing documentation. VARK is a theory of learning preferences. It’s an acronym of visual, auditory, read/write, kinesthetic.

“VARK captures various preferences for taking in and implementing information where learning is the objective. This makes it extremely useful for writing documentation. Thinking about how your users process your information and how to make it as easy as possible for them is helpful. When writing, think about the different ways that people engage with and process the information your provide; VARK argues that there is a spectrum for the way people do that.” ~ Siobhan McKeown

Engage via format

Once you have an understanding of the breadth of learning styles you’ll need to address, format comes into play. How do you want to engage? There are dozens of different formats you can employ, from glossaries and tutorials to screencasts and videos. The types of media that can be brought to bear are effectively unrestricted.

Communications tips

McKeown also includes a set of communications tips that are nearly universal. She suggests the following:

  • Keep it simple.
  • Refer to the user in the second person.
  • Stick to the point.
  • Think about formatting.
  • Write in the present tense.
  • Think about tone.
  • Don’t be afraid of short paragraphs.
  • Be logical.
  • Proofread.

You can see the whole list of documentation creation tips here. It’s one of the most in-depth and useful articles on technical writing I’ve found, and it’s worth checking out.

Editor’s note: Siobhan McKeown will be speaking at WordCamp Europe at the end of the month on the topic of “Bringing Ideas to Life.” WordCamp Europe draws attendees from around the world, and GoDaddy is honored to be the Diamond sponsor for WordCamp Europe 2014.

Image by: buechertiger via Compfight cc

Christopher Carfi
A veteran of both startups and the enterprise, Chris has a deep track record in developing customer community and evangelist programs for brands such as Adobe, H&R Block and Aruba Networks while holding executive positions at Ant’s Eye View and Edelman Digital, and he was co-founder and CEO at Cerado. He currently lives in the Bay Area with his family.