Last night I joined the Vonage Developer Day live stream for a single presentation, Lauren Lee’s “The Art of Technical Writing”. Her talk’s objective was to motivate developers to write technical tutorials and provide them with the basics they need to get started. Lauren has an unusual background because she was a high school teacher before switching to a technical career, so this means she knows a thing or two about education.

The talk was incredibly fast-paced due to her passion and energy, so I had a hard time keeping up with writing notes, nevertheless I want to give you a little (subjective) summary.

Lauren says developer content should be instructional, non-assuming, timely, correct, and concise. The crucial points here are non-assuming because we often make wrong assumptions about what common knowledge entails and timely because technical content may get outdated soon. If you don’t know what to write about, “write the article you wish you found when you googled something.”

When it comes to creating tutorials, she suggests getting early feedback on an outline before starting to code and write. Then, implement the application and keep a journal or good commit comments that form the basis of your writing. After coding, move on to writing as soon as possible, so the memories of your challenges are still fresh. Edit later. Take time for the revisions and, again, get feedback.

A developer tutorial should start with an introduction, set a goal, explain the prerequisites, and then go through the necessary steps. It’s not required to document the whole codebase, just the essential parts. Include screenshots or animations. Put a summary at the end, and don’t worry about repetition; some of your readers reach here after skipping over other parts.

Some of Lauren’s general writing advice includes using a conversational tone without simplification words, inclusive language, and avoiding references that might be outdated soon (something I wrote about lately, too). And, of course, practice!

Once you’ve published your piece, share it loudly. Send it to people and look for cross-posting opportunities. Analytics tools are your friends to find out what works.

I enjoyed this talk. Though I have a lot of experience writing on this blog, the CloudObjects blog, and creating content for my clients, there were still some new or good aspects to hear about again, that will help me get better at my craft.

So, what are you waiting for? Go and create some amazing developer content! Or, if you don’t want to do it yourself, hire me for a contract.