I have a professional dog and pony show that I've taken on the road to various gatherings of system administrators, a talk (and song and dance) called "Why the Documentation Sucks". Yesterday I got a whole new slide and story to add to the presentation. The topic is how enormous the gap can be between the viewpoints of software developers and system administrators.
Coming down the road soon is a new version of a file system I document. Let's call the current file system MOOSE in honor of my filesystem friend mizmoose. So the new file system is MOOSE2. For months I have been asking how MOOSE2 will differ from MOOSE from the point of view of administrators, and the answer is always, "Oh, there won't really be any difference for them. The differences are all internal." I bring up this question a lot on cheese day. I read all the bug reports looking for issues related to the user interface, but nothing seems to fall in that category. Ok, that's the background.
So do I need to produce a separate document, or just say that the MOOSE document is now the admistrator's guide for MOOSE and MOOSE2, since, as I kept learning, there is no difference in the administrative interface? The other writer here and I decided yes, which might seem odd, but the logic is that all further development will be for MOOSE2 which might, conceivably, affect the actual user interface and we will still need to support MOOSE so setting up the structure in this way makes sense even if it seems cumbersome to have two virtually identical manuals.
What happened yesterday is that the project muckamucks, casting about for new areas to be concerned with, decided to focus on documentation. Ok, I said, so I went to copy over the MOOSE manual as a MOOSE2 manual and to try to figure out what I needed to say about the purpose of MOOSE2 in the introductory sections. The kindliest developer in the office told me that he actually had written up a few paragraphs about the differences between MOOSE and MOOSE2, but it was all internal stuff and probably wasn't anything I could use. Oh, I said, that would be great. It would be a start. Thanks a million. I didn't know this existed.
I looked at what this guy sent me and, as part of a parenthetical aside, there was a reference to the very basic file system creation command, one that every system administrator ever setting up MOOSE2 filesystems would need. And this command had a DIFFERENT NAME than the parallel command for MOOSE. This was, um, a revelation? Well if there's a new command then there's got to be a new man page. I found a system I could log into that has MOOSE2 installed to check the relevant man page and try to figure out what the deal was.
It was like opening Fibber McGee's closet.
The man page I checked sent me looking for another new man page I hadn't know about. Well, why would I think there were new man pages if there were no changes to the administrator interface to document? And then that man page sent me to another, which summarized a whole bunch of related commands. What ultimately became clear was that EVERY SINGLE FILE SYSTEM COMMAND HAS A DIFFERENT NAME for MOOSE2, except MOUNT but even there you have a new required parameter to specify.
What this means is that even though from the point of view of the user "there isn't really much difference between administration of MOOSE and MOOSE2 filesystems", EVERY SINGLE EXAMPLE IN THE ENTIRE MANUAL IS WRONG.
Now it's true that everything an administrator does is basically the same for both file systems, down to the intricacies of locking protocols and cluster support. It's also true that all of the basic options are the same for the functionally equivalent MOOSE and MOOSE2 commands. From the point of view of the internal kernel code guys, this really is no difference, in terms of what sort of parameters the user is specifying for them to deal with. Also, presuming the existing manual is ok, I don't really have to write a new manual, I just have to replace all of the existing command references and examples with command references and examples that use the new command names for MOOSE2. That's a few weeks work, rather than a few months work.
So really, there is no difference here between MOOSE and MOOSE2. Except, oh, for absolutely everything the administrator needs to type.