Ask HN: How do you find good documentation writers? | Hacker News Reader

Ask HN: How do you find good documentation writers?

2 pointsjayparth3 comments

I've been looking to hire a writer to help out with documentation, but I've had a hard time finding someone who has experience writing really good developer-focused documentation. Most tech writers from big companies like Microsoft just aren't able to write clear and concise documentation.

Does anyone know what places I should look for good tech writers? Or any recommendations

View on HN

The problem with documentation is that they're generally written by the developers themselves and are burdened by the curse of knowledge. A lot of bad documentation I've dealt with is often riddled with acronyms and a priori knowledge of underlying systems and external dependencies.

I think a good approach is to hire junior developers/interns and just ask them to build stuff off your API from scratch and carefully record their pain points, questions, etc. As a bonus, the stuff they build can also later be used as working "best practice" examples -- assuming you get your developers to code review them.

I say junior developers because they're a good knowledge baseline to aim for and are probably not "contaminated" with a priori knowledge of your system or similar alternatives.

Probably someone who is a developer or has been a developer in the past who has also written articles or blogged a lot on technical issues. The problem is that tech writers tend to get paid less than developers so if you are a decent developer who writes you are probably not going to want to switch career path. Hence you get technical writers that do not actually have development experience.

In my experience, the writing of developer docs is much less important than:

- making it easy to find what I want (good search, helpful table of contents, etc.)

- lots of examples for every method signature or REST call

- complete use-case writeups with runnable examples

If you noticed I said examples multiple times, then I think I've made the point I intended to make.

Reply on news.ycombinator.com