3 ms·
Ship Types, Not Docs
- jameskilton 8mo agoAPI 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/ https://diataxis.fr/
- HeavyStorm 8mo agoHaven'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.
- pbronez 8mo agoHuh I thought the canonical reference for this was https://docs.divio.com/documentation-system/ 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 8mo agoThanks, you're probably right, this is what I was looking for but I guess my search-fu failed.
- limoce 8mo agoWhat about using LLMs to automatically update docs?
- tommy_axle 8mo agoso like GraphQL?