Comment by whataretensors | Hacker News Reader

Comment by whataretensors | Hacker News Reader

Parent Full thread

One of the hardest things to do is choosing the right battles. Ask, is this worth it? If it's an API integration point primarily for internal use I wouldn't insist on it. If the API is changing too much right now that documentation would quickly become obsolete, I wouldn't worry about it. It might be easier and cheaper to get a backend engineer to answer your questions.

If you are expecting clients to integrate with your backend without documentation, and you do not have an enterprise-level agreement, then it would be a deterrent for integration on most teams. Making that case should be straightforward. More documentation would mean more adoption, which means more value for the company.

In my opinion this is a very important battle, even if this will be a 100% internal API. Think about the possible scenario - no one touches one of the endpoints for 18 months. A new developer comes in and wants to use it. There are no docs and no one remembers what's going on there. == mess.

This is the issue I am mostly worried about. Not having documentation is risky, as it causes your team to depend on human-resources instead.

or the code.

depending on this API, it could just be easier to look at the code. Seriously, if it is just exposing some database tables, then I don't necessarily always see the point of extra documentation. With extra docs you have to answer:

    * Who writes the docs?
    * Who reads the docs?
    * Where are the docs?
    * When are the docs written?
    * How are the docs written?

Basically, unless you have a dead-simple process, or a docs champion, you've just created another project. If you can answer these questions:

    * Who writes the codez?
    * Who reads the codez?
    * Where are the codez?
    * When are the codez written?
    * How are the codez written?

Then the simplest thing may be "just read the code"

Reply on news.ycombinator.com