logoalt Hacker News

fauigerzigerkyesterday at 9:17 AM0 repliesview on HN

>Somehow I doubt at this point in time they can even fail at something so simple.

I think it depends on your expectations. Writing good documentation is not simple.

Good API documentation should explain how to combine the functions of the API to achieve specific goals. It should warn of incorrect assumptions and potential mistakes that might easily happen. It should explain how potentially problematic edge cases are handled.

And second, good API documentation should avoid committing to implementation details. Simply verbalising the code is the opposite of that. Where the function signatures do not formally and exhaustively define everything the API promises, documentation should fill in the gaps.