| Congrats on launching! I regularly spend time on developer documentation (just yesterday roughly two hours...). Unfortunately, your messaging does not resonate with me at all. Creating (good) documentation will never be easy, or hassle-free. We have to communicate/teach technical concepts to a wide range of developers, from beginners to experts, from native-speakers to I-barely-understand-english. Having a huge document with lot's of details is bad, because one can't grasp the big picture. Not documenting all details is also bad. Having multiple documents per topic (e.g. a Getting Started/Tutorial and a full reference) is a hassle to maintain. I believe Documentation Review is at least as important as Code Review. What you think you're communicating, and what others are understanding, may be very different. Having at least one other pair of eyes look over it is extremely helpful. It is also helpful to maintain a consistent writing style if several developers contribute to the documentation. Some things that may make my life easier: - Help me keeping my writing style consistent (e.g. "In this case, foo should be used" and "In this case, you should use bar" are not consistent) - Help me keeping my text easy to understand (like http://hemingwayapp.com) - Help me keeping multiple documents in sync (e.g. "You've changed foo_bar to fooBar in reference.md, you should also look at tutorial.md lines 25 and 34") - Help with the workflow coordinating multiple reviews (we're actually using Github PRs, and I don't see much room for improvement) |
We provide you #1 on a golden plate, saving you many hours per year of designing, coding, maintaining servers and working on integrations.
For #2, we are still getting started. We have been working with tens of technical writers in small, medium and large enterprises and we understand the problems that exist throughout this step. Look out for some amazing features that are coming soon.