Essay, Mindfulness, Writing

A Guide to Writing Guides: a meta-guide


FastCompany satirizes furniture assembly.


James Joyce by C. Ruf, Zurich, 1918

James Joyce by C. Ruf, Zurich, 1918

You’ve been tasked with explaining a process to your colleagues, clients, or end users. You remember those needlessly nightmarish instructions for electronic appliances and furniture that fold out into a quilt of pages. You have no desire to produce such literature.


You already notice this guide is easier. The prose so far has relied on simple declarative sentences. You’re ready to increase user satisfaction, and you can do so by communicating UX design and product features in an informative and empathetic way.


Why am I your guide if I have a B.A. in English and an M.F.A. in Screenwriting? I earn income by writing instructional text and technical documentation. I don’t think most children say that when they grow up they want to be technical writers.


But it happens. We all need to work. Even if you’re James Joyce, you have a day job. Joyce taught English in an area of Austria-Hungary that is now Croatia. And so this is what I do now while I work on publishing my novel People Without Names.



1. Underestimate the technical skills of your users.


There are few things in the world more poisonous to UX design than the philosophy of “If users don’t know this, they have no business using our product.” That’s the religion of developers who believe all their technology is intuitive and all their armpits effuse jasmine. This assumption is crushed when users search nonexistent FAQ pages and email support teams with questions.

Empathy means being mindful. And being mindful means understanding that users are not necessarily developers of products and tools. Write documentation that elaborates. Avoid documentation that is so concise that it is esoteric.

2. Use everyday language in your prose and simple sentence structures.


Draw an OwlWriting documentation that elaborates does not mean writing verbosely. It means writing enough so that methods are sufficiently explained, and it means simpler diction whenever possible. Ironically, “esoteric” should not be used as I did above.

This also applies to instructors in other disciplines. If you’re teaching high school biology, it’s better to say that a mole is an “underground” mammal than a “subterranean” one.

If you must use technical vocabulary—and sometimes you must due to a lack of synonyms—they cannot be mentioned casually because users may not know them. Introduce them. Unpack their concepts.

The instructions on the left satirizes the omission of key steps and concepts.



3. When possible, use typography an advertiser would use.


Advertisers and e-commerce websites deliver the least amount of information that enables their customers to make a decision. They achieve this through sentence fragments and words that are designed in a scannable way rather than a traditionally linear fashion. In general, people read the Web this way.


GiftRocket designs their homepage in a scannable way.


Although you are not writing ads, you should be grouping information into digestible amounts. As Elephant Journal recommends in its style guide, “It’s best to break up long paragraphs. It makes longer posts easier on the eye and less intimidating.” It’s also helpful to:

  • List related ideas in bullet points.
  • Use line breaks often.
  • Create section headers.
  • Organize headers in a table of contents.


4. Examples give credence to concepts.


Examples can serve as supporting points in essay writing, and they can also turn on the metaphorical light bulbs over your users’ heads. I’ve already used examples in this methodology on methodology. If this guide gets any more meta, I’m going to start addressing you by your first name.


5. Illustrate concepts with images.

The Starbucks mobile app has intuitive UI.

The Starbucks mobile app has intuitive UI.


An accompanying image is one type of example in your guide. It’s especially useful when a program lacks intuitive UI.


Of course, if the interface suffers from this, the design should be changed. However corporate bureaucracy and financial resources can prevent a redesign, and the design will be fixed and fucked indefinitely.


That’s where you come in.


No, you won’t be able to un-fuck the design, but you will be able to point out features in a screenshot.


Remember something that Peter Hornsby, Web Design and UX Manager at Royal London, said:


Probably the most difficult thing of all is accepting that sometimes you cannot deliver the best design you’re capable of—just the best design that you can deliver within the context in which you’re working.”




6. Test the instructions yourself.


As much as you can be your worst enemy, you can also be your best Quality Control inspector. Follow your own guidelines and verify them. You may have overlooked a step or you may have phrased something in an assuming way. Avoid being that instructor who tells someone to “draw the rest of the fucking owl.”


7. Have someone test the instructions.


By now, you’re aware that this guide is really about empathy, mindfulness, and humility. You must know that even after testing the instructions yourself, you can still omit key information.

Solution? Peer review. Editors are your ally. I receive useful feedback from my Content Development team at Alelo Inc. Your company or organization should allow time for review and revision, if it values its end users. Cast suspicion on companies that do not allow this. It speaks to a larger issue, and you may want to seek employment elsewhere.

I don’t have any advice on that topic, but I can direct you to a Glass Door.

—Tommy Tung

Move with Accord Progression

on Facebook

Visit its sibling site Fiction, Mostly



Quality Metrics


Aspect Quality Standard Metric
Content 1. topics are appropriate a. all relevant topics are included
b. topics are explained to the target audience without assuming they are as technically trained as the developers
2. sections make sense a. order of information is useful for troubleshooting
b. headers reflect their topics
Text and Images 1. upholds standards of readability a. prose relies on everyday language
b. multisyllabic words are not used often
c. sentences are not all composed of multiple clauses
d. sophisticated concepts are broken down
e. typography uses best practices in Web design and advertising
2. examples are helpful a. common concerns are described
b. images are provided when it is difficult to rely on words alone about the product interface
c. examples reflect the advice of the section rather than contradict it
3. passes peer review a. comprehensible to a colleague
b. theoretically comprehensible to a user



About FictionMostly



No comments yet.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: