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 whataretensors on Tuesday October 11, 2016 @12:52PM (#12686129)

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.

[ Parent | on HN ]

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 ]