Ask HN: Does your company document internal APIs?

1 points by larkfofty 4 years ago | 2 comments

I'm a frontend engineer with about ~5 years of experience now, including at a small startup, a FAANG and now at a recently IPOd "unicorn".

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.

WheelsAtLarge 4 years ago |

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.

PaulHoule 4 years ago |

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.