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

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.

Besides convincing your backend team that sharing how to communicate with the API in a structured way is important, one bit of advice in general is to make it easy.

One way to make API documentation easy is to generate it from code rather than write a doc manually. This can pull from class and method comments to add description to your endpoints (if those comments exist and are relevant), but even if they aren't there you'll still have access to the endpoints and the input/output.

I'm not sure what your tech stack is but here's an example using Django w/ Django Rest Framework. You can use Swagger [1] for docs / a browsable interface to the API. Then you can use an integration like Django Rest Swagger [2] to automate most of the work.

[1]: http://swagger.io

[2]: http://marcgibbons.github.io/django-rest-swagger/

what is the language & middleware/framework used in backend ?

I've often found if you lead the effort yourself, and then ask for their input, this usually works well. If you wait for someone else to take the first step, it's usually not going to happen.

Start by creating a Github wiki for documentation for both front-end and back-end API's. Add them as collaborators, or create them right inside each existing repo if you can. Populate the back-end one as best you can to your knowledge, then ask for them to validate.

I always think of documentation as a note to my future self. In X months, what won't I remember?

I'd argue that this should go the other way around. Your developers should be creating the 'docs' - the API design and boilerplate, before programing it. If they actually sit down and design the API before setting of to write the code you'll end up with: (a) the documentation you want. (b) an API that this designed consistently and consciously. Would you let your front end developers build something without at least a wire frame / functional design?

Everything comes down to time and budget. Assuming you have a project budgeting model, make sure that for every project you add in estimates for analyzing, documenting, and integrating the backend layer, and call it out specifically as a result of insufficient documentation. What you're trying to do is get someone up the managerial food chain to ask, "Why are we paying developers to do this for every project, when we could document this once and be done with it?"

To put it another way, you'll never have enough leverage to talk another business unit into spending their time and money to solve your problems. You need to make your problem someone else's -- someone with the ability to force the solution.

There is a cultural problem in some orgs where some (even sr.) devs think not documenting things creates job security, but it really just creates bottlenecks that suffocate the organization. Few things signal a corporate death spiral like the phrase, "useless documentation." This means that nobody is going to read it, because nobody cares, and nobody cares because it's probably crap. GIGO. A product of shitty thinking.

The only real value of any software is that it does what someone says it does, and if nobody says it does anything, then I would argue it is not creating value for anyone. It is showing up to work and consuming resources, but it's not moving the company anywhere.

Growth in a company means building things that are the foundation for something else, and those foundations are based on the assurances of people with credible word. Documentation creates a basis for that credibility. A lack of credibility means a lack of ability to deliver value.

If your backend devs won't document their APIs as a matter of backward principle, your company is probably in a death spiral, fire them or eject.

/r/whataretensors is correct that you have to pick your battles. However, if you're asking us then I'm going to assume that the lack of documentation is slowing you down enough that it is in your company's interest for docs to get written. Lack of docs puts timely product delivery at risk.

What are the product-owner's overall goals? You should tie documentation to that. In a healthy organisation, the product-owner's goals will either be already pretty clear or they'll be actively working on making them clear. If they aren't clear to you then do a quick check through emails/minutes/retrospectives to see if you've missed something and ask for a half hour on their calendar to seek clarity. Take the bulk of that time to listen[1] to what their priorities and stressors are. Pay particular attention to where your work fits into that. If your work actually doesn't fit into that then you've got a bit of an organisational incentives problem. Assuming it does, then make your case that documentation in a canonical place (even if it is those same json files and some comments) is not a nice-to-have but a need-to-have for frontend to deliver what the product owner needs.

For all of this, I've assumed that the product owner for the backend and frontend is the same person. If it is two different people, then you might have a conflict of incentives that needs to be fixed: The backend team has little/no incentive to help the frontend team. If that is the case, then you should have a chat with the product owner of the frontend team because that is an organisation-level problem and some incentives will need to get re-aligned.

[1] https://hbr.org/2016/07/what-great-listeners-actually-do

I would think long and hard about the following questions:

What are your expectations?

What is the minimum possible that could be done to meet your expectations?

What deficiencies currently exist that are blocking you?

Once you have this written down, only then should you approach the other party. Remember YOU think it is "messy" "lacks docs", however others may think it is fine. You will not win any friends by demanding someone does more work that they don't consider to be worthwhile.

If you have no leverage, then you are asking for a favor.

Be nice, be friendly and courteous. Try to see the other person's viewpoint.

Good luck in your negotiation.

If it's just an internal use, you can ask them to have tests build against the endpoints and use that as a way to document how to use them. It's better than nothing, and they're technically code, so it's in their domain to build.