What if the process documentation isn't confusing and stupid because the author is bad at explaining things - what if the process documentation is stupid because the process is stupid and needs to be changed.
Another approach to this kind of thing is to reverse the sequence of "do it", "document it" steps and draft a rough version of the documentation up-front as part of an initial design, while it is cheaper to change the process or system, before work is done to implement it and roll it out.
Both groups fell into child-like glee when it was explained to them that SEI level 1 involves writing down your current process as it actually exists. Which meant they got to describe the dumb stuff they'd been putting up with for years, with various degrees of tongue-in-cheek humor, satire, and sarcasm.
- Send boss email
- wait 2 hours for reply
- bug boss about email
- find out IT Guy already left for the day
- Resume process in the morning
Things like that, and a good time was had by all.
I think it's great for greenfield work. Forget existing solutions, if you were looking for a solution, write out how you'd ideally like it to work, after it's written, figure out if you can create something that works like that
The apex of the argument came down to documentation quality, and at first I thought this conversation was over and A won a bunch of points. I forgot about it for almost a year and then it came back into my brain, moved into the upstairs room, and has been trying not to pay rent ever since. And this is what is playing in a loop in my head:
I was really excited about this thread until I read your reply. And now all I can think is 'why is their documentation bad?' prejudging it before even looking at it.