Do Tech Writers Need Paragraphs?

It’s a disingenuous question: the answer is obviously yes. Consider, though, how often you write one when you might not need to, and whether a reader might be able to extract the necessary information more quickly.

(No shade meant to the paragraph. I love paragraphs.)

I’m explaining how to do something. Use a list of steps.
I’m persuading someone to do a thing. Sure, you can use a paragraph–also consider bullets, or a table.
I’m creating reference information. How about a table or diagram?
I’m teaching someone a skill. OK, but maybe give them hands-on activities?
I’m clarifying how something works. Maybe, but diagrams are good too.
I’m explaining why something does something. Go for it!  Paragraph!
I’m describing something. OK, but:
1. Make sure you have a good reason to describe it at all!
2. Would a picture or diagram help reduce paragraphiness?
I’m describing a user interface.

You poor thing. Here is some whiskey.

Please don’t write paragraph-length descriptions of a UI. If you can’t have screenshots (lots of reasons why not), your UI is truly baffling, and the UI team can’t incorporate field descriptions on screen, how about a definition list or table?

Leave a Reply

Your email address will not be published. Required fields are marked *