[CMake] Documentation strategy

[Brandon Van Every]

On 6/21/07, Philippe Fremy <phil at freehackers.org> wrote:
>
> To see an example of a project taking advantage of doxygen for general
> documentation, you can check Yzis - http://doc.yzis.org .

Doxygen is certainly a broadly accepted standard in open source.  I
just don't know if anyone has done wiki <--> Doxygen in an
off-the-shelf reproducible way.

> > 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.
>
> Given the current quality of the doc, I think it would work better if
> the cmake doc would simply be imported into the wiki, so that people can
> improve it.
>
> > Then you run into the problem of "how
> > do we ship wiki docs?"
>
> That's the real question. Given the content of the wiki now, it would
> already be a valuable addition to ship with the existing documentation.

This has a history in the bug tracker, which you can read about at bug
#3757, "ship FAQ as part of documentation."  At that time, Kitware
said it's too much work to maintain a shipped FAQ or other wiki
information.  I agree that without an infrastructure to handle wiki
<--> docs, it is too much work.

We got URLs to the wiki in the documentation, at the very end of the
docs.  This works fine for Unix man pages, where they're the last
thing you see as you scroll the man page, and it's in the expected
place for that sort of information in a man page.  It is not fine when
reading the docs in a HTML browser on Windows.  It's at the very end
of the docs and will almost never be read.

I entered a content bug some time ago, #3907 "Windows start menu links
for online documentation."  That's a logical place that Windows users
go to look for docs.

I've entered a new one, #5225 "put wiki URLs at top and bottom of docs."

> > What people really want is docs that work
> > well with their chosen IDE.
>
> Before that, a slightly more generic documentation of CMake concepts
> would be welcome. Quoting and variables is for example a topic that is
> not really covered anywhere. For me, the behavior was quite strange
> (different than what I expected). I had to rely on lot of
> experimentations to understand what CMake is doing.

Yep.  That's bug #3676, "Table of Contents for documentation."
Recently, Bill and I had a long, private discussion about all the
content bugs, and what is to be done about them.  My conclusion is
that Kitware doesn't have the resources to address these things, and
the community has to find a way to do it.  The process for modifying
the docs is too cumbersome for the community at present.  The
community has to devise a better infrastructure, or this situation
will persist indefinitely.

> That's probably covered in the book, but I find it strange that you need
> a book to be able to use an open source tool like CMake. Maybe I am too
> used to high quality documentation ?

Not at all.  The vast majority of mature commercial products out
there, open source ones included, have high quality electronic
documentation.  CMake can either provide that like everyone else does,
or fall by the wayside over time.  There's too much competition out
there for people to accept this situation indefinitely.


Cheers,
Brandon Van Every