Technical Writing - 5 Tips

I've recently returned to the Midwest after having lived for 22 years in California. I grew up in Fargo, so I won't be surprised by the weather, but I do look forward to being surprised by the creativity and writing talent here in the Twin Cities. Having worked for Microsoft and also currently running my own consultancy, I have been involved in technical writing for over 20 years. I have written (or ghost-written) for Google, Amazon, Microsoft, and many other major technical companies.

In addition to having published three technical books, I've authored countless articles on data and cloud topics. While in California, I worked with a number of new technical writers. Based on these experiences, I'll share my top five technical writing tips here.

1) Don't assume knowledge. Spell out technical acronyms and define concepts.

2) Write for an audience. Programmers have different interests than business development types, focus your writing accordingly.

3) Write at the correct level of detail. Closely related to the previous point, developers enjoy detailed information about HOW a technology works, while biz-dev types prefer reading about WHY their customers would want to use that technology.

4) Write for a medium. If publishing on the web, write using scannable techniques, such as bulleted lists, rather than long paragraphs of text.

5) Test your writing. Ideally, test with at least one person who represents your audience. If no one is available, at minimum, read what you've written out loud.

I am happy to be back in Minneapolis and look forward to meeting the writing community here.