Comment by wwweston
2 years ago
I'm not sure whether the issue is stack complexity / depth, but there is definitely something in the culture where it's common for docs and how-tos and Q/A to tell you what to do, the steps/commands/etc, but to do little to help you build any kind of relevant domain model.
This isn't exactly new, there's always been documentation like this, but I think the proportions have changed dramatically since even the early 2000s.
One of my vaguely defined theories is that as valuable as automation is, the culture of automation / process has started to diffuse and act as an influence on how we think, in steps & commands rather than models.
Possible that we've always been steps-results / input-output beings, but I wonder.
I recently created some documentation for a process at work where I explained the 'why' for most of the steps and commands. Not in great detail, but just a bit of detail. I thought that it was good as a step-by-step recipe, while also giving context that could help someone in the event that something didn't go according to plan.
I was asked to remove much of the context that I provided, so as not to confuse the reader, and to make it as direct as possible. This is documentation intended for experienced, technical professionals. I think that the revised documentation is less helpful.
I had the same thing. I took the reader through the journey of "why" they should want to work in this way, but apparently that's confusing.
That actually the important part though. If people don't know why they are doing something, they don't do it.
Perhaps you could compromise by moving the “whys” into an appendix to the guide with references from the “how” section.
Perhaps it could be restructured to separate out the howto from the explanation to serve the reader’s intended use at the time as described here: https://diataxis.fr
As a tech writer I love the concepts of Diataxis but don't agree with it being invoked here. Context is critical in all four of its quadrants, and its model doesn't apply uniformly to every aspect of every application.
GP did IMO the right thing by understanding the audience first in order to judge what level of context is appropriate. That should be rule 0 before anything in Diataxis gets involved.
1 reply →
Everyone wants a quick fix these days, in all parts of their life.
How to do X in [an hour, a day,one week of lunches, 30 days.] Heal yourself from X in [an hour, a day, one week of lunches, 30 days. ] Eat/Dont eat this get slim in [ one week of lunches, 30 days, 60 days]
A long time ago I studied martial arts (Karate). Our structure went up to the master in Japan. Once you got past the orange belt, the only way to progress was when the master was visiting. the master also decreed that you had to have a belt for min 1 years, in brown 2 years. in black 4 years before you could try to graduate. He said people needed to grow into their skills and mature.
I haven't thought much about that until a few years ago a colleague told me her daughter had just gotten her first black belt. Knowing her child was no more than 12 that seemed odd, but she had studied hard for almost 2 years.
That seemed like some form of fast-food martial arts.
By pure coincidence I met the son of my previous master at a train . I knew him but the last time I saw him he was still a kid. He was Japanese as well but he spoke excellent English. Something his father had no interest in. He had taken over from his father and was now the master. We talked a bit his dad, the clubs. I mentioned this rapid progression that my coworker's daughter had done. He leaned back and laughed a little.
"Ah, we call those dirty white belts"
A little like coding bootcamps I think.
Yes, too many cookbooks, "with solutions and examples", and no one writes good reference manuals any more.
I kind of get it. I think about a problem, and I am solution focused. Furthermore, I want to learn what I need to implement the solution, and usually don't pay attention to other features that are not directly related to my problem.
However, by giving me a cookbook, the documentators are doing me a disservice in two ways: first, they are greatly limiting the amount of solutions I can use. If my problem is not something they already imagined, I need to find another cookbook or read their source code to find out how to solve it.
And second: they are taking away from me the process of learning about the different parts of the system and how to integrate them into a solution by myself.
And the gotchas are endless. I am using FastAPI and the amount of things I have no idea how they work underneath, until something fails, is mind wrecking.
I wish there was some real reference manual of it, not just the autogenerated function signatures and the most minimally useful documentation I have ever seen. So many things make no sense, and I have to second guess the FastAPI designers all the time.
> there is definitely something in the culture where it's common for docs and how-tos and Q/A to tell you what to do, the steps/commands/etc, but to do little to help you build any kind of relevant domain model.
So very true and this is actually my biggest complaint with MSDN nowadays. It's so difficult to built a mental model of what's actually going on, which makes the documentatino difficult if your needs aren't exactly what the documentation is describing.
I don't know when this phenomenon started but it drives me batty.