Hacker News Reader

Comment by iddogino | Hacker News Reader

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.

View on HN

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