My lab is hoping to rework a toolkit’s documentation to follow Diátaxis principles. Or, more honestly, to follow any principles other than just being whatever was easiest to write.
So, um, how do we do that?
Reusing what we already have
We do have a wiki. It has issues, but it does exist. I won’t throw the baby out with the bathwater. Epecially as we do actually want most of the bathwater, just with a different organization.
Without a strained metaphor: we’d like to rescue and re-use as much pre-existing documentation as possible. Perhaps we’ll split up articles, add more content, fix outdated stuff, etc. But keep what we can.
What we probably can’t do is reuse everything directly. Our current articles don’t fit nicely into the Diátaxis categories. And, as previously mentioned, there’s outdated stuff. Broken links and old workflows and such.
Change everything at once?
Yes, the ideal scenario would be waking up tomorrow to completely fixed documentation. You know those magic helper fae that come into fairy-tale homes at night to tidy up? That would be nice. Unfortunately, as far as I am aware, magic helper fae do not exist. Especially not magic documentation helpers.
So the reality is that we probably can’t fix everything all at once. There’s simply too much stuff in there. What we can do is work in parts. Take an article and spiff it up to be more modern. Split it up if needed, fill in missing parts, figure out how and where to link it.
The only thing that does probably need an initial revamp is the homepage, but that’s just so that we know how everything will end up organized. Aspirational edits, if you will. Then we can fix everything else to match.
Coordinating with others
No single person can fix all of the documentation, for the simple reason that the only such person is probably Adam Novak and he’s too busy. That means that we’ll have to work together to get everything fixed up. We’ll also need team buy-in to maintain the documentation in this fixed-up state.
Having channels outside the documentation is important here. Having ways for people to bring up problems without needing to know a fix is also important. Having agreement that better documentation is a goal with some priority? You guessed it, also important. Probably the most important of them all.
How do you do all that? I… don’t really know. A lot of my cleanup projects have been single-person jobs, and that’s because I found that often folks are much more willing to talk about grand plans for clean-ups than willing to roll their sleeves up and do it.
But I guess that’s just another “how people work” question. And I’ve always been bad at that subject.
Well that’s a depressing note to end on. But hey! At least I’ve documented (heh) my thoughts, so when I actually start this project, I’ll be able to remember what I was so worried about.