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

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

7 pointsameesdotme19 comments

I've been working at a SaaS-company for about half a year as a front-end developer, the product has been in production for about 3 years. The codebase has always been quite messy, because many engineers worked on it without any guidelines or even linting.

In the past months, the front-end team worked on a new application that is well documented and maintainable. This resulted in the need of two new APIs.

This resulted in an exchange of JSON-files over email, rather than a proper API-documentation. I am currently in the process of trying to convince the product-owner to allocate time for this, as I'm quite disappointed about the total lack of docs.

Do you have any tips on how to take this on?

View on HN

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"

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/

There are other tools/plug-ins to generate OpenAPI/Swagger spec (1.2 or 2.0) based on annotations in the code. Please refer to http://swagger.io/open-source-integrations/ for more information.

If the REST API is documented in OpenAPI/Swagger spec, you can then use Swagger Codegen [1] to automatically generate API clients in Java, C#, Javascript, Typescript, Ruby, ObjC, Swift and more.

[1]: https://github.com/swagger-api/swagger-codegen

Disclosure: I'm a top contributor to Swagger Codegen

+1 for swagger.

We are a C# shop and it's awesome how our XML comments flow into the docs seamlessly. Makes documentation almost zero extra work.

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.

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?

The problems I've found with this approach are:

1) It is hard to write clear explanations of things that you don't understand.

2) It adds another project to your plate. If you don't actually allocate time for this project from what you are currently doing, it won't get done well and it will distract you from what your primary responsibility is.

EDIT: So, OP would need to convince the product owner that he should spend his time on docs rather than javascript.

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?

Good point. How can you build an API if you don't know what data to return anyway? Designing a model is part of the job and could be documentation by itself. Thanks!

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.

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

Python / Flask

using node.js/express here and I share your pain/ Need to find a module or should I write one which automates major part of documentation.

This has python support.. might be helpful : http://apidocjs.com/#examples

Reply on news.ycombinator.com