6 ms·
Ask HN: How do you find good documentation writers?
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
- smt88 6y agoIn 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.
- bryanrasmussen 6y agoProbably 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.
- trinovantes 6y agoThe 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.