Hacker News Reader

Comment by aasasd | Hacker News Reader

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.

View on HN

This [0] helpful resource distinguishes between tutorials, reference material, how-to guides, and explanations.

[0] https://documentation.divio.com

Indeed, 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.

Yup! 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.

Oh 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

Swagger ‘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’.

The 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.

GraphQL tooling exposes enums as such, I believe

In 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.

My 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.

I 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.

Reply on news.ycombinator.com