Skip to content

Latest commit

 

History

History
107 lines (68 loc) · 12.7 KB

resources.md

File metadata and controls

107 lines (68 loc) · 12.7 KB

Technical Writing

There are a number of resources relating to technical writing, scattered around the web and in print. This is a (growing) list of technical writing resources. Pull requests to add titles are encouraged. Please add the title and a brief summary following the style below. For articles that are available on the web, provide a link.

Books

The following books are not all specific to technical writing. However, their advice on general writing definitely applies to technical writing as well.

Written by a professional technical writer at one of Silicon Valley's most exciting companies, Modern Technical Writing is a set of guiding principles and thoughtful recommendations for new and experienced technical writers alike. Not a reference manual, and not comprehensive, it instead serves as an introduction to a sensible writing and publishing process, one that has eluded the profession for too long.

Zinsser describes writing as a craft, comparing it to carpentry. He focuses on teaching you how to edit, claiming that first drafts are never good. The earlier chapters provide general writing and editing advice, while the later ones are topic-specific and cover travel writing, technical writing, memoir writing, etc.

This book teaches the lost art of rhetoric in a highly entertaining fashion. Each chapter is an explanation -- containing many hilarious and self-describing examples -- of a simple rule to make your writing sound better and be more persuasive. You can read it cover-to-cover, or open it at random.

'On Writing' by Stephen King

This book is half an autobiography of Stephen King and half writing advice. Although it is aimed more at fiction writers, the advice is generic and sound. The intimate descriptions of the hardships King went through before becoming a famous writer are inspiring.

'Trees, maps and theorems' by Jean-luc Doumont

Doumont runs training courses on scientific and technical communication. His book, subtitled 'Effective communication for rational minds', is aimed at technical people who want detailed and practical advice about how to communicate clearly. It does this in a highly structured way with plenty of examples. Later chapters also give advice on presentations, graphical displays and posters. It's also an obsessively edited book. Each minimalist double-page spread has one column of body text and three other columns for common questions, illustrations and examples –– and if you look closely you'll see that the paragraphs have been tweaked to be perfectly rectangular.

'Style: Toward Clarity and Grace' by Joseph M. Williams

A slightly older book but still very worth a read. William's strength lies in identifying and naming what it is about difficult sentences that actually makes them difficult for humans to parse. The book starts at the level of individual sentences, walks through plenty of examples of how to polish them for maximal clarity, and later moves onto showing how to build coherent paragraphs and larger bits of text.

'Practical Typography' by Matthew Butterick

Formatting and layout of text on a page or screen is an area of writing that's often overlooked or thought of as "someone else's job". However, with the modern prevalence of independent web publishing, where the writer and typographer will often be the same person, it's useful to know the basics of good typography. In describing their typography, Butterick also covers concepts valuable to technical writers such as effective emphasis and how to best present lists and hierarchies of headings.

The book is available online only at http://practicaltypography.com/ -- as payment, Butterick encourages a donation or a purchase of one of his excellent fonts.

Linguist Steven Pinker takes an analytical approach to writing in this style guide, with chapters about reverse-engineering good prose, seeing the grammatical trees in sentences in order to untangle them, and how a writer's intimate knowledge of a subject may distort their writings about it (the biggest problem with much academic and technical writing). Much time is also spent investigating the rules of English grammar and dispelling the many myths that have grown up around it.

'Technical Blogging' by Antonio Cangiano

This book is, as you may have guessed from the title, specific to technical blogging. "Successful people often get recognition by teaching what they know. Blogging is a reliable path to do that, while gaining influence in the process." Unlike most of the others here, it doesn't focus as much on writing well, but more about how to set up a technical blog, how to promote it and how to find time to write.

A free e-book that covers the role of a technical writer, practical guidance for writing technical documents, and working with the rest of your team as a technical writer.

Articles

'Writing well' by Julian Shapiro

A free handbook in five parts that covers what to write about and how to rewrite to be clear and succinct, available online at julian.com.

'How to Write with Style' by Kurt Vonnegut

Vonnegut presents 8 concise rules. He reminds us to 'sound like ourselves' -- something which is perhaps more difficult but still important in technical writing.

This aims at language use for user interfaces, but it has many nice rules with concrete, short examples for each. The sections on Tone and Punctuation are applicable to general technical writing.

Essays on CIA writing

This is an interesting, but not that useful, collection of essays about writing well. They are from 1962 and were originally classified, but have since been released. You'll find the usual "avoid the passive voice and jargon" type of advice. The original essays can be found here and a higher level write-up about them here.

A crowd-sourced list of axioms and rules of writing, along with descriptions, thoughts, and examples. You can find the whole list on Stack Exchange.

Blogs

A blog written by professional tech writer Tom Johnson on numerous topics including technical communication, processes for managing docs, and information usability. Most well-known for its popular API documentation course.

Websites

Website run by technical writer Marc Achtelig since 2004. Most well-known for its popular Technical Documentation Tool and Web Guide, which lists hundreds of tools useful for technical writing, for its collection of free AutoHotkey scripts for technical wrters, and for its various code snippets for improving online documentation.

Videos

A Youtube video aimed at academics, but very generally applicable writing advice, and why everything you learnt in school is probably wrong.

Style Guides

Used by Ritza for technical tutorials and other developer materials.

Used for all tutorials on the DigitalOcean community, this style guide is opinionated but a good starting point for writing tutorials that are widely accessible and engaging.

Used by technical writers, editors, and content managers working with Microsoft products. You can fork the repository on GitHub to propose changes through a pull request.

Used in the Aerospace and Defense industry, S1000D is an international specification for the procurement and production of technical publications. Using XML, this comprehensive styleguide helps to facilitate improved maintenance, logistics, and after-market support.

Courses

Google Technical Writing Courses

A collection of courses for writing clearer technical documentation and improving technical communication skills. The pre-class material is a helpful guide. There are also in-class materials and exercises available to practice technical writing.

Learn API Technical Writing Course Series by Peter Gruenbaum

A series of three courses for technical writers who want to learn how to write API documentation. They teach how to document structured data, focusing on the two most popular structured data formats: JSON and XML. If you are new to API documentation, this is a great place to start! No programming experience is required, but technical writers with programming experience who want to know more about structured data will still find it useful.

Course about writing documentation for REST APIs. You’ll learn about endpoints, parameters, data types, authentication, curl, JSON, the command line, Chrome’s Developer Console, JavaScript, and more. You’ll learn about the required sections in API documentation, analyze examples of REST API documentation from various companies, learn how to join an open-source project to get experience, and more.

Meta

Something as meta as writing about writing would not be complete without a meta section of its own. Here are some articles that already collect and describe other works on writing.

Good Plain English: The problem with writing manuals

Nat Segnit discusses six books about writing, providing entertaining examples, some focused on contemporary American politics. http://harpers.org/archive/2017/03/good-plain-english/