There are 3 types of documentation:
1. Why/what 2. API spec 3. Tutorial
You need all 3. They are distinct, use different styles, and exist for different purposes and audiences.
1. Why/what 2. API spec 3. Tutorial
You need all 3. They are distinct, use different styles, and exist for different purposes and audiences.
Explanation (why, what)
reference (API spec)
tutorials
How to guides
This same set could be easily "transposed" to the contemporary world of web. With all the proper indexing. Why is this "art" "lost" for most of the software :-( ...
BTW, one Excellent incarnation of this documentation art is on the front page right now:
Before the internet, the printed book was all you really got. That meant the company distributing the software had to hire technical writers who'd work with the software devs to create all of this, send it to an editor, and ultimately get published.
We no longer live in an era where tech companies hire tech writers. Software documentation lacking is something that can and limp along with jira cases and support services sold rather than trying to put in the upfront effort to fix everything.
Now, for open source software, hate to say it but the docs have always been pretty crap. Certainly some stands out (usually when the business model was around providing services on top of open source software), but nobody is really paying anyone and few people really want to do that sort of free labor.
The writers can't do their work without input from the technical side and the time for that is often not avaliable.
I know I've been punished for taking time to push ideas to tech writers. Not only does it slow me down in other places, it often gets swept away as unnecessary changes because upstream Sr techs disagree.
For example, when I modify ssl configs, I alway reference the files with soft-links. This makes it so you don't need to modify the config files and simplifies keeping old and new certs so you can flip back during the overlap period you should be providing to test. I try to avoid editing production files by hand whenever possible because in my experience it introduces the possibility to create errors.
I rewrote some docs extending alot of areas with example commands showing how to test things, with explanations that fleshed out the previous quick and dirty documentation. I also modified the method from copy and replace certs, edit files, restart service; to copy files, replace or create soft-link, restart service.
Upstream approvers trashed the whole thing because the thought it was unnecessary and disagreed with me about manually editing config files.
Or so much better than the competition that people use it in spite of poor documentation. Many things like that also grow a cottage industry of people making documentation and teaching (see React or Rails).
Tutorials are teaching a method, like which ends of the pliers you grab. They do not assume a lot of domain knowledge.
HowTos pick the user up where she stands with a concrete problem and walks you through a possible solution of that specific problem. Like how to use pliers to twist a wire just firmly enough to hold two things together.
How to calculate the airspeed velocity of an unladen swallow, etc.
Why don’t they use their proposed system to explain their own system?
It seems like a wasted opportunity. So odd. Or am I missing something?