[CMake] Documentation strategy

[Brandon Van Every]

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.

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.

I'm not sure wikis are the answer either.  I do add things to the
wiki, but I don't think wikis really cause a lot of people to make
significant doc contributions.  Then you run into the problem of "how
do we ship wiki docs?"  One answer is you don't, you force the user to
access the internet and use the - typically very limited - wiki format
for their lookup needs.  What people really want is docs that work
well with their chosen IDE.  In the Chicken Scheme community we've got
some people working on wiki --> TexInfo conversion, because they are
so irritated with all the docs being on a wiki.

It seems like a really basic infrastructure common to a lot of open
source projects.  Reminds me of the motive for distributed rather than
centralized version control systems, like Darcs and Mercurial.  I
haven't looked around to see if anyone has come up with a better open
source doc paradigm.


Cheers,
Brandon Van Every