Open Source Documentation, Again

I had a whole blog entry written, but sadly the new and "improved" Blogger application appears to have eaten it. Personally I don't think they have improved the application, as ^Z after setting something to a block quote now appears to delete the complete entry contents, the preview is way less friendly in the new popup format, and the editor icons don't seem as intuitive as they used to. Overall I think I'd rather go back to the previous version, but there doesn't seem to be any way to do that.

Anyway, to cut a long story boring, I just wanted to point out that when I went to update my Cygwin installation (hoping that Python 2.6 and/or 3.1 would now be available, which sadly they aren't - where's Jason Tischler when you need him?) I got a parse error on the setup configuration file. No biggie, the setup program even pointed out that I probably needed to download a new copy, and when I did so the updated copy told me to read the Cygwin documentation to find out what I needed to know to update from 1.5 to 1.71 (I presume 1.6 was omitted for some reason).

Sadly when I went to the Cygwin home page the only relevant information I see is "PLEASE read the new User's Guide before upgrading your Cygwin installation to 1.7. You're avoiding trouble."

This is OK, but when I follow the link to the users' guide I get a list of three different possible formats plus links to two different quick start guides and another link to Setting Up Cygwin. It's only by clicking one of the users' guide links that I finally discover the link, in the table of contents, to What's new and what changed in Cygwin 1.7. Guess what? None of the information in there relates to upgrading from an earlier version, so I am left with the only hint being the note at the start of the home page that says

Please note that the update from Cygwin 1.5.x to Cygwin 1.7.x might require some manual changes afterwards. Most notably the mount point storage has been moved out of the registry into files. User mount points are NOT copied into the new user-specific /etc/fstab.d/$USER file. Rather, every user has to call the /bin/copy-user-registry-fstab shell script once after the update.

Now I don't want you to think that Cygwin's documentation is lousy. In fact the situation might seem less problematical if the documentation were worse, but generally Cygwin is up there with Python and Django in terms of the quality of its documentation. All of which only makes it seem more jarring that there is no specific advice to use migrators, even though the project home page seems to imply a) that there is, and b) that it's important to read it.

Anyway, I am going to finish this post now, before Blogger decides it's time to delete all my typing again. Happy New Year!

EDIT: Interestingly the original entry came through on Feedburner, but I decided to leave the revised entry as it was, modulo this edit. As is so often the case, a re-work improved the quality of the work.