3 ms·
Well, I guess the most important part of docs is ... examples! Give your users examples, from which they can derive, how to use parts of your library. Those exa
by zelphirkalt 7y ago
Well, I guess the most important part of docs is ... examples! Give your users examples, from which they can derive, how to use parts of your library. Those examples also better be explained in natural language as well and not just somewhere in a git repo, so that the user does not need to build a mental model of the ideas of your library first, before being able to understand your examples. Oh and did I mention diagrams would help? As a professional group, we truly suck at documenting things properly.
Many people think, that docs are done once they auto-generated API docs from source code. They are not. That's not something that deserves the name "documentation". Auto-generated API docs are among the last things to turn to, when there is nothing else around or when you already understood the ideas of the library and only need to look up a name of something. That's not only true for Rust, but also for other languages.
- quietbritishjim 7y agoExamples are the most important part of you docs sometimes. There are at least two reasons for visiting docs: * Want to understand generally how to use a new concept, typically at the class level (or more trickily at the two-or-three-classes level), e.g. how do I create a thread? * Already familiar with the concept but want to do something specific, typically at the method level, e.g. how to test whether a string starts with a particular prefix? There was a good post on Hackers News a few months ago breaking down documentation visitors into four categories, so there's at least two more. I think examples are very important in the first case, typically you want an example led-approach to explaining new concepts. But examples are a lot less important for method-level questions, and are often (not always) totally redundant if you have really clear and precise information about the method and its parameters. Edit: But just to be clear, I agree that examples are really important and you should definitely put them in your docs (at the class level and above). Edit 2: Here's the article [1] and HN dicussion [2]. In that terminology, I was distinguishing "explanation" and "reference". The other two types are "tutorial" and "how-to guide". [1] https://web.archive.org/web/20200312211539/https://www.divio.com/blog/documentation/ https://web.archive.org/web/20200312211539/https://www.divio... [2] https://news.ycombinator.com/item?id=21289832 https://news.ycombinator.com/item?id=21289832
- imtringued 7y agoYou're stumbling over the distinction between "user guide" and "API reference". Both count as documentation but they have completely different goals.