[CMake] Documentation strategy

[Brandon Van Every]

On 7/12/07, Alan W. Irwin <irwin at beluga.phys.uvic.ca> wrote:
> On 2007-07-12 13:39-0400 Brandon Van Every wrote:
>
> > On 7/12/07, Alan W. Irwin <irwin at beluga.phys.uvic.ca> wrote:
> >>  In contrast, using a browser to search through
> >> html results would be painful.
> >
> > Do you mean it would be painful under some new regime with multiple
> > html files?  When there's a single html file, like with the current
> > docs, it's trivial.  You hit "Edit.. Find in This Page" in your
> > browser.
>
> It's a personal preference.  I tend to like CLI's over GUI's since 10
> fingers have much more bandwidth for a touch typist than a mixture of
> mousing around and keystrokes that you tend to use for GUI's.
>
> Also, the browsers I have tried do not have the powerful regular expression
> searching you can do with "less".  As they say, "less is more". :-)

I'd say that simply Finding a substring has solved 99% of the RTFM
problems I've ever had.  If you don't find what you're looking for on
the 1st go, you find it on the 2nd or 3rd go.  I think it's a stretch
to call it "painful."  Fairer to say it's "not ideal for a Unix
keyboard regexp guru."  I'm comfortable recommending Find... to any
user, techie or non-techie.  It's a simple skill and it gets the job
done.  Really the only skill is telling people they should search for
things, and that they should keep looking if they don't find it on
their 1st try.  A surprising number of people lack that skill.  But I
expect that widespread computer and internet literacy will eventually
lead to widespread search literacy.

Anyways, my point with regards to docs is, as long as they're
searchable, they're usable.  The current CMake docs are 1 monolithic
HTML page, but at least such a page is searchable.


Cheers,
Brandon Van Every