4 ms·
My long-standing annoyance with software documentation is when people don't see that tutorials and reference are different things. They may have tutorials as th
by aasasd 5y ago
My long-standing annoyance with software documentation is when people don't see that tutorials and reference are different things. They may have tutorials as the only documentation available (ahem Ansible cough), or reference as the only documentation. But in fact, the use-cases for those two are different, so effectively they have different audiences. I don't want to learn a language from a dictionary, and I don't want to wade through the tutorials when looking for one particular concept.
- k__ 5y agoI think, reference only can work when it's really really good. But generally you're right, guides/tutorials for the main use-cases speed up things drastically.
- xtiansimon 5y agoSwagger ‘documentation’. I understand every programmer I talk to loves this auto generated ‘documentation’ (prolly for selfish reasons). For me the tautological definitions, and lack of overview (which resources you need to form basic reporting—my introduction was swagger api for a Platform POS) undermine the description as ‘documentation’. I’m not complaining about what Swagger does, but about the cavalier way other programmers and vendor managers sound all chipper about their (un-)helpful ‘documentation’.
- nonameiguess 5y agoThe number one thing killing me about auto-generated API documentation is when an API takes a "string" that is really an enum and the generated documentation doesn't list out the enum values. Your only recourse is to read the code if it's open source and available in some obvious place, or hope there's a GUI alternative to the API with a pick list, select every option on the list, and intercept the internal API call it makes to get the string representation of each allowed value. Looking at you, Nexus Repository Manager.
- ldarcyftw 5y agoGraphQL tooling exposes enums as such, I believe
- dmlorenzetti 5y agoThis [0] helpful resource distinguishes between tutorials, reference material, how-to guides, and explanations. [0] https://documentation.divio.com https://documentation.divio.com
- aasasd 5y agoIndeed, that was the first time I've seen someone clearly voice more-or-less the same view, when the link previously appeared here on HN.
- solarmist 5y agoYup! This helped me immensely when I started writing documentation more regularly. In the past I used to mix all 4 and ended up confusing everyone.
- DavidPiper 5y agoOh wow, I literally have a blog post queued up about how different kinds of "documentation" can be split into similar categories. Great to see that someone else has had a similar insight! My categories are Source (Reference), Procedures (~Tutorials), Examples (How-tos) and Meta (Tribal Knowledge, history, etc). In the context of software teams (and others I'm sure) my anecdotal insight is that without a balance of these kinds of information, certain team functions break down: - No Source/Reference, no shared deep understanding - No Procedures, difficulty scaling processes (and difficulty onboarding new team members) - No examples, harder to develop new skills / level up existing skills - No meta, no context or "why", leading to less motivation
- 3pt14159 5y agoMy biggest annoyance with software documentation is when it only has simple examples and doesn't mention obvious corner cases or covers the case where there is one related object but doesn't cover the case where there are multiple objects.
- mapgrep 5y agoIn open source the trend unfortunately seems to be toward a Readme.md with a couple of simplistic examples, then you’re left to read the source in lieu of a proper API reference. I still remember CPAN perldocs as a high water mark for docs. They had specific sections for examples, starting with the summary at the top, and another for proper reference. And more importantly a strong culture of good docs. The examples tended to be close to comprehensive, progressing from simple to complicated problems. Then there would be a rundown of arguments and return values for the key methods.