4 ms·

>documented with awkward English Sorry, not everybody on Earth has perfect English. The author has a point about APIs being UIs but remarks like that make me t

>documented with awkward English Sorry, not everybody on Earth has perfect English. The author has a point about APIs being UIs but remarks like that make me think his expectations are a bit too idealistic.

sverhagen 6y ago
Of course if your audience prefers a different language, let's substitute English for the other language. If your point is that a good programmer (of APIs) may not write perfect documentation (or even bad documentation), maybe that's exactly where you could treat your API as a first class citizen and bring in a technical writer. I'm not saying that's worthwhile for every API being developed. But if you want to build a first class product, and bring in designers and what not for the UI, why would you neglect the API.
- dgudkov 6y ago
  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.
- porpoise 6y ago
  You mean "substitute that other language for English"? ;)
  - sverhagen 6y ago
    Yeah, I suppose. English also happens not to be my first language :-)
arp242 6y ago
It's not that hard, and native English speakers are just as bad at it as non-native speakers. The problem isn't with less than perfect English language skills, it's about just taking some care to ensure it reads nice by using appropriate interpunction, paragraphs, is reasonably comprehensive, doesn't just lazily tack on "oh, this too" lines at the end instead of rewriting the paragraph, and things like that.

sverhagen 6y ago

Of course if your audience prefers a different language, let's substitute English for the other language. If your point is that a good programmer (of APIs) may not write perfect documentation (or even bad documentation), maybe that's exactly where you could treat your API as a first class citizen and bring in a technical writer. I'm not saying that's worthwhile for every API being developed. But if you want to build a first class product, and bring in designers and what not for the UI, why would you neglect the API.

dgudkov 6y ago
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.
porpoise 6y ago
You mean "substitute that other language for English"? ;)
- sverhagen 6y ago
  Yeah, I suppose. English also happens not to be my first language :-)

arp242 6y ago

It's not that hard, and native English speakers are just as bad at it as non-native speakers. The problem isn't with less than perfect English language skills, it's about just taking some care to ensure it reads nice by using appropriate interpunction, paragraphs, is reasonably comprehensive, doesn't just lazily tack on "oh, this too" lines at the end instead of rewriting the paragraph, and things like that.