Researching for Technical Writing

How are technical articles and books written? It all comes down to research. Every editor I've worked for has always extolled the importance of research, and a well-researched article is certainly more pleasant to write.

The following suggestions are based on the methods I employ intuitively, so I may have missed out some important points. However, I hope it gives readers some ideas on how they can bolster their own technical writing.

Reader Competency

First, decide who your article is for, and what they already know. Writing for beginners means drawing on standard documentation, and perhaps putting more creative effort into example code.

Writing for more advanced developers requires more work. When targeting readers at this level a huge amount of effort should go into understanding deeper issues. For example, rather than researching core libraries, I'll research more involved problems such as structuring or scaling large applications.

Community

The community around a given technology generates a wealth of research material. Try reading mailing lists, blogs, social networks, and Hacker News/Reddit comments. This really helps show what areas commonly confuse people, and therefore what might be worth writing about.

When researching Windows and Node: Portability, I found several relevant posts to the nodejs Google Group by prominent developers in that community.

Issues

GitHub and similar services provide issue tracking. Bug reports and feature requests give amazing insights into the problems users have.

It can even be productive to see how the authors fixed bugs, because it might demonstrate an interesting technique or a weakness of the underlying technologies.

Related Projects

Don't just look at the core technology that you're covering, but also read about prominent related technologies.

If I wanted to write a book about Ruby, I wouldn't just research Ruby and its core libraries, I'd also focus on its major open source projects. Researching the Rails community would give big clues as to how people perceive and use Ruby itself.

Source

Finally, any time spent looking at the technology in question's source code is time well spent.

When I write about Node, I always have an editor open with Node's source code in it. This helps me expand on material in the standard documentation, and also learn techniques straight from the developers who made the technology I'm writing about.