Technical writing tip

Filed under: design

tl;dr. A picture is worth a thousand words.

Oftentimes [web] developers need to write instructions for humans, to communicate technical concepts to end-users that use the code they wrote. Often times the human who has little familiarity with code languages will find the messages cryptic. Adding a lot of technical detail is impressive and all but it doesn’t help to accomplish the goal of communicating to humans about technology.

How to write a good step by step tutorials? The #1 Tip: Describe the context. Pictures are not required but can help so much.

How to take screenshots: Popular browsers (chrome, firefox) have extensions (i.e. Awesome Screenshot) for taking screenshots of webpages. Install that, and use it for marking up the image. It gets your user to focus on the exact place of the image that you’re talking about. You could also label them (i.e. 1,2,3,… or A,B,C,…) if you have multiple things to talk about.

Annotated screenshots makes it convenient for me to say with little bias that AWS has terrible UI/UX. EC2 directions

Annotated screenshots helped me emphasize to folks the need to install a particular version of OSX CLI.

Here are some examples of diagrams that have worked throughout history:

Describing Steps

Describing how pieces fit into a whole

600px-Diagram_of_the_human_heart_(cropped).svg

Notice that both of these use multiple colors, arrows, and different types of lines to show different concepts. Quick sketches such as these are are not the same as blueprints, which are another form of graphical representation that requires precise measurements and much longer time to produce at a decent quality.

Disclaimer: My general experience as a writer includes providing editing feedback for scholarly publications, writing technical & business proposals, creating UI/UX deliverables to various stakeholders, writing README files for open source projects, writing up issue tickets, and providing QA-related evidence. As a reader I have critiqued many a textbook diagram and DIY instruction manual.