Ask HN: Back-end team does not document their APIs. How do I convince them?

Re:Ask HN: Back-end team does not document their APIs. How d... by iddogino on Tuesday October 11, 2016 @01:40PM (#12686602)

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.

[ Parent | on HN ]

Re:Ask HN: Back-end team does not document their APIs. How d... by ameesdotme on Tuesday October 11, 2016 @02:02PM (#12686867)

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.

[ Parent | on HN ]

Re:Ask HN: Back-end team does not document their APIs. How d... by new_hackers on Tuesday October 11, 2016 @04:22PM (#12688189)

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"

[ Parent | on HN ]