[CMake] Documentation strategy

[Brandon Van Every]

On 6/20/07, Alan W. Irwin <irwin at beluga.phys.uvic.ca> wrote:
> On 2007-06-20 10:56-0400 Brandon Van Every wrote:
>
> > On 6/20/07, Philippe Fremy <phil at freehackers.org> wrote:
> >>
> >> All in all, CMake is a good and powerful tool, but I find that the
> >> documentation is lacking behind. More structure, more usage example,
> >> more common cases would in my opinion really help the user experience.
> >
> > Well, you can buy the "Mastering CMake" book.
>
> However, that is terribly out of date and paper so I have never been tempted
> to buy it.

I wonder how "terribly" out of date it is.  Last time I was worried
about that, Bill said it wasn't.  I believe we had that discussion at
the release of CMake 2.4.6.

Paper is bulky, and it's not updateable.  It is easy on the eyes
though.  Sometimes I gotta get away from computer screens in order to
contemplate stuff.  LCD screens are definitely better on the eyes than
CRT screens though.

I've never personally felt the slightest need for a book to tell me
how to use CMake.  I learned CMake the "open source hacker" way.  In
fact, doing that drill over and over again with many broken open
source Windows projects, is what led me to CMake in the 1st place.  I
knew what I was trying to accomplish, I surveyed the field of
available build tools, and I saw that CMake was the best of what was
offered for C/C++ projects.  Also I had a memory of downloading the
VTK once upon a time, and that it actually built.  Quite a rarity for
Windows open source projects, and I had seen tons of 'em.  So
inadvertently, I had already seen CMake in action.

But clearly, other people need good documentation when they're
evaluating a tool.  They don't always have clarity of purpose, they
are often "just browsing."  They aren't going to buy a book to do an
evaluation.  My own metric for how good the documentation needs to be,
is "good enough to keep a CMake newbie on the hook long enough to
become an intermediate user."

> the subversion book
> (freely downloadable from http://svnbook.red-bean.com/ in a number of
> editions and translations) is a huge lifesaver, and I think it is one of the
> fundamental reasons why subversion is finally overcoming CVS's
> "first-to-market" advantage.  The analogy between subversion and CVS on the
> one hand, and CMake and autottools on the other is pretty good in the sense
> that you have outstanding new software that replaces the old, yet there is
> still a huge pool of people using the old software because of that old
> software's "first-to-market" advantage.

A flaw in the analogy: everyone hates and wants to dump CVS.  People
will inevitably move on to something better, there's just this huge
latency in the installed base.

In contrast, the Unix-only crowd doesn't have much reason to drop
Autoconf / Automake.  They'd like their build times to be faster, but
that's not enough to pull them away from the old comfortable drill.

The projects that see CMake as a slam dunk, are the ones that did an
Autoconf build for the Unix stuff, and also had to maintain some
horrible hand rolled Visual Studio build, typically with .BAT files.
They get sick of the pain that the Free Software Foundation is
deliberately causing them.  The FSF won't support Visual Studio at
all, even though several open source solutions for the problem are out
there.  They say, "It would harm the GNU Project."  Projects that have
made it to a truly cross-platform stage of development, have a strong
incentive to look for something better than Autoconf / Automake.

But, CMake isn't the only cross-platform tool out there.  Just as
Subversion isn't the only source control system.  If you want to dump
your legacy CVS or Autoconf, there are lotsa competing products.  Some
of them threaten to be good.  This is where CMake's docs trouble me.
If a newbie gets a frustrating experience out of the docs, he'll move
on to something he thinks he likes better.

> > There's this strategic problem that modifying the CMake docs and
> > submitting patches for them is cumbersome.  The auto-doc structure is
> > fine for documenting individual functions, but it provides no
> > structure at all for general concepts encompassing many functions, or
> > CMake operative principles in general.  I haven't looked into whether
> > there's a good answer for this, although at some point I may.  It's a
> > basic infrastructure problem.
>
> Excellent point.

And if it's not addressed, open source tools that *do* address it will
beat CMake.  Maybe not today, maybe not next year, maybe not in 3
years.  But in terms of Grand Strategy, yes they surely will.
Widespread acceptance, becoming a "de facto" standard, simply cannot
happen without first class documentation.

It's important to realize that almost everyone on this mailing list is
an Early Adopter.  With the mentality of an early adopter, i.e. very
comfortable with loose ends.  Too comfortable.  The docs are passable
for us.  They aren't passable for massive deployment.

> Excellent points. I think of wikis as rough drafts of documentation so a
> wiki to "real" documentation language (TexInfo, docbook, or whatever)
> converter is a great idea. I was interested enough to do a google search for
> (wiki docbook conversion), and I particularly liked one suggestion I found
> which was to make software to convert wiki information into the APT (almost
> plain text) format, and then from that format you can convert into anything
> you like (see http://www.xmlmind.com/aptconvert.html).  I bet somebody has
> already made a rough Wiki to APT converter (which is all you would need),
> but I have not found it yet.

I've bookmarked that.  I don't have time to evaluate tools and
approaches right now.  I do hope there's something out there already,
that's sufficiently mature, that has enough of a community behind it,
that it's worth staking a claim on.  For a strategic problem like
this, it can't be the work of just 1 key author.  People like that can
get tired of their projects and leave you hanging.


Cheers,
Brandon Van Every