I wouldn’t ascribe evil motives before the more obvious answer. Manual pages are plumbing – dirty, smelly work. There’s a reason it’s not all done yet, and the answer is *not* because distros haven’t demanded it.

The man page generation is the onus of the upstream. Yes, anyone downstream, such as a distro, can contribute a man page, and it does happen when it’s important to someone.

I’ve been involved in man page discussions over the years, such as part of Red Hat Engineering Docs and in the Fedora Documentation Project. It requires a staffing effort. There are, quite frankly, other more important books to write. It’s also not nearly as much fun, and people aren’t drawn to do it.

That doesn’t mean the distros *shouldn’t* try to solve this, and it in fact is a fairly good cross-distro collaborative item. But it’s going to require someone(s) passionate enough to drive the right people across the distros. It could in fact be customer contributors, or a tech writing class at a University, or a set of document writing sprints, or …

On the flip side, I wrote a lot of documentation for a couple of projects and wished I didn’t because it attracted more people to the project but eventually we realized that development had essentially stalled (virtually all patches were being ignored) and it would be better for people to use other solutions.

CMake is neat, yeah, but damn are their docs bad. Even two years later, apparently. I was playing with it, trying to convert a tiny project from Autobreakage to CMake (don’t know why, really; sdl_svg is completely unmaintained, at this point), and it took hours of frustration, searching, and finding non solutions to the same problems. And I never got it building on multiple machines; the lecture ended.

If anything, I don’t think you emphasise documentation enough, even. It’s part of why I choose to ignore the jeers and frowns that come my way when I reveal that I’m a Gentoo Linux user: We still have some of the most comprehensive Linux system configuration documentation out there and CURRENT.

For some reason, people seem to think they can write docs once and that’s all there is to it. But the reality is code changes; systems change; technology changes. (Then again, are you primarily a Windows user? If so, how much does the Windows app space deal directly with the gremlins of Windows’ ever-expanding ABI-soup?) If you don’t have a dedicated QA/RelEng team, you had best get used to the idea of always going back over your documentation. This is one place the automatic doc generators can really help; they make the trivial-but-numerous changes mostly transparent.

Speaking of _good_ docs, I think I need to bring up Imagemagick. Most everything of theirs is very nicely documented, formatted, and interlinked, and usage examples abound. Granted, any time you start delving into the arcana of it use, you quickly begin to grasp that the name is no joke, but at least the docs are helpful. It’s how documentation of an end-user application should be.

Inkscape also tries something novel by encapsulating the tutorials and all their directions into regular SVG. They’re not half bad, as it goes; being able to follow the directions of the text and move things around right there is pretty neat.

Personally, I wish I had a better grasp of the vocabulary used to efficiently make good technical writing; I’ve done documentation before, and it really sucks if you don’t know what the requirements actually are. It also sucks to see some of the things you’re up against.

But the Cygwin thing…very lame, guys; very lame. Windows people, in general, seem to have funny ideas about release numbers and installing “beta” software, but that doesn’t excuse that sort of treatment.

You know, I’m just sort of glad that people are starting to at least get that a tiny numeric increase is a tiny patch that probably has nothing but important bugfixes. Might make the creeling question about “new maps?” and other such things less annoyingly prevalent. (Yeah. Right.)

Disclaimer: Typos, nonsense, and rambling are the fault of a drunk keyboard. Also exhaustion. D: