Ask HN: Does your company document internal APIs?
2 comments
We are constantly bombarded with a same advice. "Document your code," but the fact is that most documentation is out of date almost as soon as it's created and no one wants to update it. It's just easier to read the code. Also, programmers get paid for code not documentation so there's little incentive to document.
Yes, everyone should document their code but no one wants to and it's almost useless in no time.
I don't know the fix.
Yes, everyone should document their code but no one wants to and it's almost useless in no time.
I don't know the fix.
I believe in "pain driven documentation" where you write up the the things that have you scratching your head.
Counter to that is the idea that documentation is opposed to "don't repeat yourself", that any documentation at all is a burden to maintain.
Counter to that is the idea that documentation is opposed to "don't repeat yourself", that any documentation at all is a burden to maintain.
No company I have worked at has actually documented internal APIs. When asking what an API returns, I've been told to either read the code for the endpoint, or to manually test the endpoint to see what it returns. If documentation does exist, it is generally a wiki doc or a hand written swagger file that was written when the endpoint was created and is now out of date or incomplete (typically the happy path 200 cases are documented but there is no documentation around edge cases or failure cases). When requesting better documentation I'm usually told something like "Yeah we'd all love to have better documentation, but it's been deprioritized because of XYZ new product work."
Is this typical? I used to think the companies I worked for were outliers, but at this point I've seen it enough times to think this might actually be relatively common.