3 ms·

I don't disagree in general. Although, as a founder, I can tell that in practice providing first-class documentation is less trivial than it sounds. Not everybo

I don't disagree in general. Although, as a founder, I can tell that in practice providing first-class documentation is less trivial than it sounds. Not everybody has the Apple's or Google's money. Technical writers are not cheap. Also technical writers tend to have problems understanding how a system works, because they lack the knowledge of the system's internal logic. Therefore, developers should be involved in writing documentation too which makes it even more expensive and tedious process. Then software changes and documentation has to be partially rewritten again. All in all, not every car is a Mercedes and not so many people can afford a Mercedes. Companies frequently don't provide best-in-class API documentation not because they are lazy (although it can happen too), but because it's always a trade-off: should the money be spent on improving documentation, or invested into new features. It's a matter of priorities and balancing between them. For some products API is the top priority, for some isn't.

dhmiller 6y ago
Some developers just write bad documentation. Some spend so much time in the weeds that when it comes time to write the documentation, they write a garbled string of words that tries to address all of the edge cases with not enough emphasis on the core usage. Others don't know how to express the concept of a feature in a simple and straightforward manner. As a member of a Developer Experience team, I can confidently say that good documentation does not require a "certified" technical writer. Good API documentation just requires that another person, who has not worked on the feature, review the documentation in code review. As a founder, it should be important to you that your business is providing the best possible value to your customers. If your business is providing an API, then you should cater to the developers who will be consuming that API as much as you are catering to the executives who will be signing the paperwork.
sverhagen 6y ago
I was trying to acknowledge the tradeof ("I'm not saying that's worthwhile for every API being developed"). I was arguing that API documentation is not bad because there is a developer with "awkward" writing abilities, rather it is bad because of choice. Which might be the best choice for your situation, but still.

dhmiller 6y ago

Some developers just write bad documentation. Some spend so much time in the weeds that when it comes time to write the documentation, they write a garbled string of words that tries to address all of the edge cases with not enough emphasis on the core usage. Others don't know how to express the concept of a feature in a simple and straightforward manner. As a member of a Developer Experience team, I can confidently say that good documentation does not require a "certified" technical writer. Good API documentation just requires that another person, who has not worked on the feature, review the documentation in code review. As a founder, it should be important to you that your business is providing the best possible value to your customers. If your business is providing an API, then you should cater to the developers who will be consuming that API as much as you are catering to the executives who will be signing the paperwork.

sverhagen 6y ago

I was trying to acknowledge the tradeof ("I'm not saying that's worthwhile for every API being developed"). I was arguing that API documentation is not bad because there is a developer with "awkward" writing abilities, rather it is bad because of choice. Which might be the best choice for your situation, but still.