Collaborating with developers – ASTC 2017
I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.
Dave Gash presented a session titled Collaborating with Developers: Challenge Accepted! I love Dave’s talks because they’re always lively, and never quite what you expect.
Dave started by saying that developers aren’t that good at writing documentation. They don’t know the syntax. It’s not that they can’t follow the rules of syntax – they do that in their day job. They’re experts in a different syntax: code.
Dave’s hint is: Don’t waste your time trying to teach the developers to write properly. Instead, fix it and move on. Technical documentation almost always starts with content provided by developers. They’re the subject matter experts, and the content is likely to be technically accurate, but their focus is different from ours.
Content written by developers has some common traits, which Dave discussed in detail:
- Assume too much knowledge.
- Dive into code too quickly.
- Branch off into esoterica—by which Dave means that they present clever and correct, but awkwardly atypical, usage examples.
Instead of trying to persuade developers to write better English, figure out how to collaborate with them. Use their content, and write what’s missing. Make their content presentable.
Some of Dave’s tips for collaborating with developers:
- Do your preparation, and make sure they know how much you know. Otherwise they’ll assume you know a lot.
- Meet them in person. Email and other non-direct forms of communication can waste a lot of time.
- Be friendly and positive right from the start. Establish common ground and make sure they know you’re interested.
- Ask open-ended questions, to prompt the developer to give background information.
- Be the student, but ask smart questions and show you’ve done your research.
- Ask the developer a question to which you already know the answer. This will help you gauge the type of answers they’ll give.
Dave gave a number of additional tips that I haven’t captured here. Thanks Dave for an informative and entertaining session!