People say you don’t know what you have until its gone. I must say that the Fedora and RHEL documentation team’s produce is certainly one thing that I do take for granted… EXCELLENT documentation! Its always there, and generally excellent, if sometimes a bit hard to find in the wiki.
Its certainly not going away, nor ever I hope! My problem comes when I need to deal with other projects for the $DAYJOB and discover other project’s equivalent systems don’t have documentation to a level I have come to take for granted. Whether its my personal projects within and around Fedora, my dayjob RHEL component or open stuff I play with the documentation is normally good.
I maintain our $DAYJOB’s “unix-build” system. This covers all the variants of Linux we support, Solaris and VMWare plus some other utility bits that are easier done with PXE boot. I’ve only taken over a lot of this platform in the last six months. In some cases I’ve not dealt with all platforms that we build, and there’s certainly some ideas I have to improve it, but generally it works pretty well and it’s generally stable.
One of the Linux variants we support is Debian. In the 15 odd years I’ve been using Linux, primarily RHL/Fedora and its derivatives but I’ve never really run it myself personally. I’ve supported it and know the day to day run time relatively well. I don’t have any thing against it or its derivatives per say, I’m just some what ambivalent towards it all!
So what does this all have to do with documentation? Well I was assigned a new $DAYJOB project which was a custom build of Debian 6. The requirements were some what esoteric and not what I would call up to the current Linux standards and expectations, especially when it came to the partitioning requirements. But my job isn’t to judge but deliver. Debian for automated installation (and standard GUI I believe) uses debian-installer, d-i for short. The documentation is well… basic. I went through, took our standard build config, updated various bits and pushed a standard build. After a few attempts… success! COOL! Not so hard…. until I tried to apply the esoteric partitioning with LVM schema that the customer wanted.
This is where it all went wrong. I thought I was going nuts! (yes, I’m insane, I enjoy every minute of it, I’m not nuts!) There was no real documentation of of the config options or their variables….. or samples. So to prove to myself that it wasn’t just me I whipped up a kickstart of RHEL. 15 minutes of kickstart hackery, push the build and within an hour I had the exact requirements. OK…. I’m not nuts! Google here we come….. lots of complaints, nothing that fixes my problems. Discover the best documentation that Debian offers….. a readme file in the code repository. oh dear! When I spoke to colleagues, friends and people i know who use Debian they either lost hope, never used it or told me they didn’t want to go back there. Ultimately what was an hour project for a kickstart based system ended up with resorting to a combination of checking of code to work out the problems and and hacking stuff. Not pretty!
So we’re almost there. The project is almost finally complete. So what do I take away from it? I will NEVER touch debian-installer again. Period! I don’t need that stress or a loss of weeks of my time! A shout out to Debian that you need to improve your documentation, this sort of stuff is what I would expect. I hear rumours there is now support for for kickstart installs, at least in Ubuntu, so that is going to be investigated.
But ultimately this is about one thing. Documentation in Fedora and RHEL, and to the people that tirelessly produce it, I do appreciate it, I always have because its always there when I need it. I just don’t always acknowledge it. So thank you to the people that produce all the documentation in Fedora and Red Hat. THANK YOU because you make my job so much easier!! I feel its easy to complain about what people don’t do so here’s a shout out for those that do do!