Archive for the ‘Technical Writing’ Category

The Tao of Topics Part 1

October 29, 2011

It’s the 21st century.

In contrast to the vast majority of history, today a significant percentage of humans can read and write. In fact, statistically, the odds of you being one of those humans is 99.9%.

Everyone who reads this blog, can read. I’d wager that everyone who can read can also write, but not everyone who can write can necessarily write well.

What does it mean to write well? From a technical writing perspective, it means primarily to write content that is clear, unambiguous, comprehensive, and coherent.

It must be clear – necessary information should be discoverable and not embedded in an “unlikely place”; it must be unambiguous – it is worded in such a way that reduces uncertainty to the greatest extent possible; it must be comprehensive – it contains all the information needed for the user to generate the complete solution to the problem provided by the technology; and it must be coherent – users should consistently use the same patterns to use the documentation.

Well-written content might also be engaging, inspiring, or entertaining, but for technical writing these are secondary. The goal of technical writing is to reduce uncertainty in users of a technology. If your documentation is entertaining, but ambiguous, or it is inspiring but has massive gaps in it that leave the user confused, then it’s not well-written from a technical writing perspective. Better flat, dry prose that gets the job done, than inspiring, entertaining prose that doesn’t!


Handwriting is so 19th century, but most of this blog’s readers still know how to do it (you are totally next-gen if you skipped it to go straight to texting). To have a conversation about “writing clearly” from the perspective of handwriting we need to talk about letters. If you don’t know what a letter is, then we have to start with understanding that before we can move on to how to write a letter clearly.

Incidentally, having people write their email address on a survey form or email sign-up list has been a bane of my existence for years. People don’t seem to realise that if I can’t read it, it’s useless. The scribbles that they put down look more like mnemonic aids than actual communication. They certainly don’t reduce my uncertainty!

When it comes to writing clear prose using a keyboard, you don’t need to focus on the formation of the letters, because the machine takes care of that for you. Then come words, where you have to spell them in such a way that others can understand them.

Text speak

Once you get the words right, we’re looking at sentences.

To write well-formed, clear, and unambiguous sentences, you need to understand what nouns, verbs, adjectives, adverbs, and prepositions are. You can write without knowing what these are, and many people do. Some people even manage a passable level of written communication without knowing this explicitly, but to have a conversation about “how to write clearly“, you need to be able to talk about what it is you are writing.

If I say: “adverbs generally weaken a sentence“, if you know what an adverb is you’ll see how “adverbs weaken a sentence” is both a test of the idea, and a demonstration of it. You’ll also be able to take the idea and apply it to your own writing to eliminate unnecessary adverbs to tighten it up and increase clarity.

My argument is that you can write without explicitly understanding the elements of writing, but writing well, and participating in and benefiting from a conversation about improving writing, requires an explicit understanding of the elements of writing.

Beyond letters with their shape and spatial relationships in writing, we have words, which aggregate these inferior units to form higher-order units of meaning. Beyond words we have sentences with their parts of speech, syntax, and grammar. At all of these stages we want to make sure that everything that needs to be there is, whatever doesn’t need to be there isn’t there, and whatever is there is clear.


Beyond letters, beyond words, beyond sentences in technical communication are topics. Technical communciation is the art and science of communicating useful information about systems. Words are the atoms of communication, with sentences as the molecules. The atoms of “useful information” are topics.

Topics are written representations of elements of the mental models that we use to interact with the real world. An expert user of a system has an internal model of the system that she uses to make predictions about how a system will act, and how a system will react. An accurate, complete mental model allows her to accurately make predictions and influence the system to achieve her desired outcomes (or know if this is not in fact possible).

An inaccurate or incomplete model is the cause of uncertainty. Technical communication aims to reduce uncertainty. As users consume technical communication they enhance and refine their internal model. The role of the technical communicator is in many cases to explicate the internal model of a subject matter expert, convert it into transmissible “chunks”, and deliver it to a user, who can then internalise the chunks, reconstruct the model, and rock out like an expert!

Topics are atomic chunks of mental models.

Just as all food can be analyzed in terms of its protein, fat, and carbohydrate content, all technical information can be divided into similar “macronutrient” groups. Both our digestive system and our brain are systems designed to interact with the world, so they have systems that reflect broad categories in the environment.

Just as the food we digest can be divided into macronutrient groups, the information our brain digests can also be divided into macronutrient groups.

Topics are exactly that – ontological categories that exist in the environment, which lead to an organ that processes these categories differently (the brain). Different topic types correspond to different physical mechanisms in the brain.

When we want to have a conversation about writing clearly we can then tackle it at three different levels: writing the glyphs clearly (taken care of by the machines now), writing sentences that are clear and unambiguous, and providing all necessary information in digestible chunks.

Just as some mixtures of food can give you indigestion, some mixtures of topics are indigestible. Think about this: it’s counter-productive to give someone elements of a mental model that rely on other underpinnings before they have those underpinnings. As an example, it’s pointless to talk about writing clear sentences to someone who doesn’t know how to write!

Let’s just skip back to those three levels of writing well:

  • writing the glyphs clearly
  • writing sentences that are clear and unambiguous
  • and providing all necessary information in digestible chunks

We have a progression here from letters / words, to sentences, to topics. Sentences are aggregations of words according to a defined structure that gives rise to sense. Topics are aggregations of sentences according to a defined structure that give rise to sense.

Let’s look at the last point in a little more detail:

Having a conversation about topics allows us to talk about how we “provide all the necessary information in digestible chunks“.

What is the necessary information? If you’re familiar with technical writing then you know that this depends on the audience. Think about topics as pieces of Lego. The mental model in the mind of the expert user is a fully assembled construction. To communicate this you can deconstruct it into its constituent pieces, and then deliver those pieces to the user, along with the assembly instructions.

Lego kit

A well-executed structured approach like this enables a user with a partially constructed internal model to quickly identify, locate, and consume the missing pieces, which are available as atomic units.

Rather than having to wade through monolithic blocks of interleaved topics, a user can quickly identify and locate the piece that they are missing.

Organising the information in topics makes it possible to provide multiple methods of locating specifc information, which I’ll discuss in more depth in a subsequent post dedicated to the topic. For now, suffice it to say that as an atomic unit each topic has a surface area, and surface area is discoverable. Think of the difference between sifting through a box of individual Lego pieces for the 3×2 green block, versus sifting through a collection of randomly joined pieces looking for it.

That’s not to say that approaching information as topics is a reductionist approach that somehow does away with top-down views, progressive disclosure, or overarching narratives – any more than considering sentences in terms of the parts of speech does away with prose.

What an understanding of topics gives us, among other things, is the ability to have a conversation about improving the information content: its coverage, clarity, and coherency for users. And that’s always a good thing.

Stay tuned for part two, where we’ll look at the “macronutrient groups” of topics – Topic Types.


The Language of Marketing

February 9, 2011

I was absently staring at a new tube of toothpaste this morning as I washed my hair. You have to look at something, right? This one declared “healthy, whiter teeth for longer”. An image of extremely long (but healthy and white) teeth filled my mind, and was immediately pushed out by the technical writer in me asking “whiter and longer than what, exactly?”

Most marketing slogans give technical writers the screaming heebie-jeebies. Not only do they make spurious and vague claims like ‘more fibre’, ‘less fat’, and ‘20% bigger’ with alarming regularity, but the adjectives! I have no doubt that it is actually possible to sell things with sentences that contain only one adjective. And if they do need more than one, I’m sure a comma wouldn’t kill them. I could rant on the folly of adverbs, too, but that is a whole different article.

Why are marketers such terrible writers?

Because customers expect spin, and spin is easy to write. All you need is a handful of adjectives and a call to action: “The new fruity refreshing Globswoddle Fizz is now available. Experience the heady taste of summer today!”

While yelling at the toothpaste tube in the morning might make us all feel better, it is not likely to turn us into marketers just to help an obviously flailing industry. I finished my marketing degree about three weeks before I decided that the marketing industry was the last place in the world I wanted to work. Eventually, I became a technical writer instead, and discovered that I had inadvertently ended up working in marketing after all. Every word we set to paper is marketing in one way or another. If it is going to be read by a customer, then it needs to sell the product. But the last thing we want to write is spin.

Why are writers such terrible marketers?

Because customers want anything but spin, and while spin is easy to write, spinless marketing is not so easy.

Spin is wanted and welcomed in places where it is expected, like product packaging and on the airwaves. When our customers read technical manuals or help text, they are looking for a solution to a problem. If they were suddenly faced with the empty promises of spin, they would lose faith in the documentation, and possibly the product.

However brutal honesty is not required, either. Product documentation should not tell customers that the product cannot fulfill their expectations. Every question needs to be anticipated and answered. The documentation must give the customer hope that their problem can be resolved, their task completed, and their sanity retained in the process.

Effective documentation never tells the customer that a product is terrible (even if it is), and it never tells a customer that they are stupid (even if they are). It never makes over-inflated claims of software brilliance, and it never assumes greater-than-average user intelligence.

Somewhere nestled in there is product documentation that shows the product in a positive light, without the hard sell. Sound easy? Like most technical writing, it sounds easy until you actually try to do it. Some tips for getting started with spinless writing:

Kick adverbs, take names.
Adverbs are a big red flag for spin. Be ruthless and cut them all out. If your sentence requires a modifier, consider what you are really trying to say. If it forms part of an instruction or description (‘The widget can be fully removed by …’), reword it to remove the adverb (‘Remove the widget by …’).

Never call anything ‘simple’.
If you tell your users that something is ‘simple’, ‘quick’, or ‘easy’, and the customer struggles with it (for whatever reason), you are essentially telling them that they fail at life. Try not to insult your users.

Mind your adjectives.
Adjectives are fine in their place. Use them only where necessary, though, and try not to use more than one at a time. (‘Locate the red button’ is fine, but avoid ‘Locate the large, shiny, red button’ that is next to the ‘tiny, silver, shiny lever’).

Know your stuff.
If you can’t describe your topic in a single short sentence, you don’t understand it well enough, and it becomes too easy to succumb to spin statements. You need to be able to give succinct and accurate descriptions for each and every component part, as well as the product as whole. If you are not able to do this, continue to research your product until you can.

Understand the enemy.
As modern humans, we are largely desensitised to advertising, simply because we are so totally immersed in it. Start noticing it. Analyse what language is used, the sentence structure they’ve employed. Work out how you would re-write it to send the same message, but without the spin.

Edit with a knife.
Never say more than you need to.


This article was originally published in Words: A Quarterly Bulletin for Technical Writers and Communicators. Volume 3, Issue 1: February 2011, with the following bio:

Lana Brindley has been playing with technology since that summer in the 80’s when she spent the whole time trying not to be eaten by a grue. She has been writing since she could hold a pencil, and is currently writing technical documentation for Red Hat. Lana holds business degrees in marketing and information systems, and with any luck will have a technical communicators degree by the end of the year. She works from her home in Canberra, Australia, and occasionally leaves the house in order to berate university students and conference goers about passive sentence construction.

This post has been cross-posted to On Writing, Tech, and Other Loquacities

Educating Developers about XML Content Authoring – The MCDUG.

October 1, 2009

In my gig as a Technical Writer for Red Hat Brisbane, I have the opportunity to work with incredibly skilled Open Source developers, and write about cutting edge technology in the Open Source software arena.

Sometimes, it is necessary to step away from documenting the technology aspects of an Open Source project, and focus on writing content that will help a team work together more effectively. I’m talking about writing documentation that supports aspects of an open source project, not what the open source project is working on. Yes, I’m talking about a procedures guide.

The Mobicents team expressed interest in taking back ownership of the community XML documentation being maintained by Red Hat. The decision had a number of positive effects:

  • Developers could contribute directly to the user documentation.
  • The open source community had access to the community content source.
  • The Red Hat Content Author (me) could focus on developing the Red Hat product documentation for the project.

Because the team was going to be writing the initial content themselves, I realised that the Self Managed Community Documentation (SMCD) project would fail quickly if the development team did not have clearly defined processes, clear grammar guidelines and support with XML authoring.

I decided to take a step back from writing content for the software, and invested time in creating the Mobicents Community Documentation User Guide (MCDUG). I had to juggle urgent documentation tasks with my MCDUG writing, but the juggling act was worth it.

I have completed the first full release of the MCDUG. The guide is hosted on the Hudson build server, and is freely available to anyone who wishes to read it. Much of the guide contains information that will only be relevant to Mobicents Developers, however there is some useful information about DocBook XML structure that may be useful to those new to XML Authoring.

I’ve been referring new Red Hat Content Authors to the structure tips contained in the MCDUG, and the information seems to be helping them get accustomed to working with XML faster. My ultimate hope is the MCDUG will be used regularly by the Mobicents developers, and will continue to evolve with the SMCD project. After all, a procedures guide is only relevant if the procedures are relevant.

Red Hat Enterprise Linux 5.4 Technical Notes – “Every Change to Every Package”

September 2, 2009

We’re getting ready to push the new “Technical Notes” document to for Red Hat Enterprise Linux 5.4.

The Technical Notes document, new for this release, contains errata documentation for every single change to every single package between Red Hat Enterprise Linux 5.3 and 5.4. In the six months between releases there have been more than 2000 changes to more than 250 packages; and every one of them has been documented for this release in a document that, at 500 pages, is the length of a short fantasy novel.

This document has been the work of a number of authors, led by Ryan Lerch, the Technical Notes author, and Brian Forte, the Red Hat errata queue maintainer. It’s also involved the collaboration of engineers throughout Red Hat, processes, and automation.

Update: The Technical Notes are now live on You can view them here.

Creating technical documentation in five easy steps

August 7, 2009

Writing a book is an adventure. To begin with it is a toy and amusement. Then it becomes a mistress, then it becomes a master, then it becomes a tyrant. The last phase is that just as you are about to be reconciled to your servitude, you kill the monster and fling him out to the public.

–Winston Churchill


Step 1: Planning – who is the audience? What are the book’s goals?

Step 2: Content – what are the chapters about? Where will you get the information?

Step 3: Writing – first draft, review, second draft …

Step 4: Internationalisation/Localisation – will the book be translated? Into what languages?

Step 5: Review – what worked? What didn’t? How will the book be maintained?


Planning and flow

July 22, 2009

After a considerable amount of struggle, I have managed to beat SELinux/rsync/Fedora 11 into submission and my chapter in managing-confined-services about running rsync on a non-standard port is just about done.

Start with properly labeled files to share (public_content_rw_t). Create a custom init script from scratch to launch rsync as a daemon as there is none shipped in the F11 distro. The script itself needs to be properly labeled as initrc_exec_t so that the rsync daemon will launch as rsync_t. If the rsync daemon doesn’t transition to this, the related Booleans (or SELinux itself) can’t be expected to have much of an effect over rsync.

So, we have a daemon in the rsync_t domain. Modify rsyncd.conf so it has a non-default port directive, which looks something like port = 10000 (in the global section of the file). Now, after starting rsync from the new init script again, SELinux will not at all be impressed that rsync has started on a port that it doesn’t expect (ie. a port that is not defined in rsync_port_t). Give up now? Never! Run:

# semanage port -a -t rsync_port_t -p tcp 10000

Still with me?

That command will appease SELinux (fussy little thing, huh?) and rsync will happily start on 10000.

This has been a pretty long battle to distill all this information from disparate sources online, IRC support channels, mailing lists and of course good old-fashioned google-fu. The world of SELinux can be quite arcane and this book is unique in that it covers real-world examples of how to enable services an administrator might configure and how to work around the problems that are commonly encountered. Let’s just say I kept finding my own book in google when searching for solutions!

Once I had all the details gathered it was a pretty quick task to get it all in XML, ready for proof-reading and minor editing. It’s become apparent to me that depending on your subject, perhaps you won’t spend so much time actually writing. This rsync adventure required a working lab setup, fully tested and confirmed and repeated before I even opened a para tag. Have everything ready, research your subject, make sure you have at least a decent outline and some sort of progression of how it will look, and the actual flow of information tends to go pretty quickly from then on.