
Ask HN: Back-end team does not document their APIs. How do I convince them? - ameesdotme
I&#x27;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.<p>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.<p>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&#x27;m quite disappointed about the total lack of docs.<p>Do you have any tips on how to take this on?
======
whataretensors
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.

~~~
iddogino
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.

~~~
ameesdotme
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.

~~~
new_hackers
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"

------
tedmiston
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](http://swagger.io)

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

~~~
wing328hk
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/](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](https://github.com/swagger-api/swagger-codegen)

Disclosure: I'm a top contributor to Swagger Codegen

------
HillRat
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.

------
fatdog
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.

------
afarrell
/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](https://hbr.org/2016/07/what-great-listeners-actually-do)

------
new_hackers
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.

------
cdnsteve
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?

~~~
afarrell
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.

------
iddogino
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?

~~~
ameesdotme
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!

------
rxbudian
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.

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

~~~
ameesdotme
Python / Flask

~~~
samblr
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](http://apidocjs.com/#examples)

