I've never seen 4doc as a command to write all 4 things. The last few places I've worked, I've always asked "Can we hire a technical writer?", because if you've worked with one that's good at their job then they have a better idea how to organize docs than we coders do.
But, short of that hire happening, 4doc helps point out where our docs are weak, by giving us a framework to discuss what any particular document 'is'. I usually find we've not got 4 kinds of documentation, but 2: a whole bunch of reference documentation, then a much smaller amount of tutorial, but little if any 'how-to' - which on the ops side, I find is what people are looking for. (the fourth kind, 'Explanation' is vanishingly rare, and usually only exists as tech talks)
I feel devs are uncomfortable with writing good how-to's because they want it DRY: either it ends up as a bunch of links out to the reference doc ("here's the bits you need, some assembly required") or they make a doc full of "if A then B", to avoid repeating parts of their answer in multiple pages. This reads terribly. A little flexibility is ok, but choose-your-own-adventure is not; just write multiple pages answering specific questions, and don't worry about the repetition.
In my current workplace, they've got stack overflow for teams filling this how-to role; I've seen many attempts at that fail due to lack of engagement but here a few people have pushed hard to make it useful and it's got some traction. We've even started using bookmarklets to pull conversations from slack and reformat them for SO.
> A little flexibility is ok, but choose-your-own-adventure is not
Now I'm wondering if you could write the how-to in Twine so that it automatically only shows the reader the parts relevant to them based on what they've chosen as they go through it :-)
edit: and having read the article, I see Julia Evans had and executed that idea already -- wonderful!
But, short of that hire happening, 4doc helps point out where our docs are weak, by giving us a framework to discuss what any particular document 'is'. I usually find we've not got 4 kinds of documentation, but 2: a whole bunch of reference documentation, then a much smaller amount of tutorial, but little if any 'how-to' - which on the ops side, I find is what people are looking for. (the fourth kind, 'Explanation' is vanishingly rare, and usually only exists as tech talks)
I feel devs are uncomfortable with writing good how-to's because they want it DRY: either it ends up as a bunch of links out to the reference doc ("here's the bits you need, some assembly required") or they make a doc full of "if A then B", to avoid repeating parts of their answer in multiple pages. This reads terribly. A little flexibility is ok, but choose-your-own-adventure is not; just write multiple pages answering specific questions, and don't worry about the repetition.
In my current workplace, they've got stack overflow for teams filling this how-to role; I've seen many attempts at that fail due to lack of engagement but here a few people have pushed hard to make it useful and it's got some traction. We've even started using bookmarklets to pull conversations from slack and reformat them for SO.