Ship Types, Not Docs
shiptypes.com
Ship Types, Not Docs
1–7 of 7 posts
Re: Ship Types, Not Docs
#2API 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".
Re: Ship Types, Not Docs
#3What about using LLMs to automatically update docs?
Re: Ship Types, Not Docs
#4so like GraphQL?
Re: Ship Types, Not Docs
#5API 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 Ty…
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.
Re: Ship Types, Not Docs
#6API 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 Ty…
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.
Re: Ship Types, Not Docs
#7API 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 Ty…
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.
Thanks, you're probably right, this is what I was looking for but I guess my search-fu failed.