[jameskilton]

API documentation / types / signature is just one of the four types of documentation[1] that every service and library should ship. The other three are for telling people the things that code cannot tell you. The OP is arguing that the only "docs" you need are "how do I call this", not "what does this do", or "what do I do with the results", among plenty of others.

So no, what the author should be writing is "Ship Types and Docs".

[1] https://diataxis.fr/

[pbronez]

Huh I thought the canonical reference for this was https://docs.divio.com/documentation-system/

But yeah the “Reference + Explanation + Tutorials + How-To Guides” concept is the best one I’ve come across for documenting technical systems. I’m planning to lean into it heavily for my next project.

[jameskilton]

Thanks, you're probably right, this is what I was looking for but I guess my search-fu failed.

[HeavyStorm]

Haven't read the post and after this comment I unfortunately don't think I will. I'm a true believer(tm) on typed code, but it is no substitute for docs.