Technical Writing

Years ago I remember coming across a comment on about technical writing. I had forgotten exactly what it said, but remembered it was short, had a snappy title, and followed its own advice.

I discovered it again. The page at the original url is long gone, but the Wayback Machine comes to the rescue:

Best Writing Advice for Engineers I've Ever Seen. Period.

How to make engineers write concisely with sentences? By combining journalism with the technical report format. In a newspaper article, the paragraphs are ordered by importance, so that the reader can stop reading the article at whatever point they lose interest, knowing that the part they have read was more important than the part left unread.

State your message in one sentence. That is your title. Write one paragraph justifying the message. That is your abstract. Circle each phrase in the abstract that needs clarification or more context. Write a paragraph or two for each such phrase. That is the body of your report. Identify each sentence in the body that needs clarification and write a paragraph or two in the appendix. Include your contact information for readers who require further detail.

– William A. Wood, September 8, 2005

More accurately, the Wayback Machine has an archive of a page on Jottit, which appears to be a pastebin-style site. It looks like Jottit is running on Heroku, and currently returns an error for any page. Shame.

Here is the original link, the original jottit, and the archived version on the Wayback Machine. Thanks William Wood, Edward Tufte, and!