On Thu, Jul 02, 2009 at 06:54:39AM +0200, Mark Burgess wrote:
>
> > So the newcomer who wants to use 3 has to go read the docs for 2
> > and then apply diffs. I don't think they could survive with just
> > the cf3 doc. That's really a turn off for newcomers.
> >
> You mispresent the documentation here, I think.
Before I go into the rest, I do want to say I appreciate your
comments below that you are trying to improve the documentation,
so please take my comments seriously. I didn't just take one look
at give up, I spent considerable time trying to get cfengine3
working, including poring over the reference manual. I found myself
numerous times having to go look a the cfengine 2 docs to understand
what was being said.
So I went through the doc and took a close look at this. I'll reword
my statement slightly -- so much of the documentation, especially
at the top, focuses on the differences, and in some cases features
are described more in terms of their differences from cf2 than in
terms of their function, that I think the newcomer can quickly feel
that the reference is a document for experienced cf2 users.
It really reads like someone started writing about cfengine3 as if
he were talking to an audience largely familiar with cf2.
In on case that I found, the reference really does say
"just like XXX in cf2" and the kicker is that there's no documentation
of that feature in the cf2 docs.
Examples below.
Try looking at references to "cfengine 2" in the cfengine 3 doc, and then
delete all sentences which give a comparison, then see if the section
still makes sense and has sufficient information. I think you'll find
numerous places where it doesn't.
I think a large part of that can be addressed by moving all cf2
references to a subsection of each section titles "Differences from
cf2," and then editing the rest of the section for completeness.
If I were a cf2 user, I'd *want* to easily find out about the
differences so I didn't have to read through every part of the doc
to understand cf3. But as a newcomer, I don't want to wade through
the discussion of differences in order to understand what a feature
does.
> I have seen users of cfengine 3 take great strides in just a few days.
I'm sure some do make great strides quickly just as you say -- there
are always people at the high end of the bell curve, but what you
don't know for comparison is how many people got frustrated and quit.
And there's no way of collecting that data, so it'll just remain
an unresolvable debate.
But consider whether you're just too close to the project to see
how the documentation looks to an outsider. I've dealt numerous
times with programmer and admins who thought that their documentation
was just fine because it made perfect sense to them, but only because
they knew the system so well to begin with. They would leave out
critical steps because they were *so* obvious that everyone should
know them, but everyone didn't. Debugging docs is as valuable as
debugging code.
FYI, I'm originally a cfegine 1 user, which we had been using at SDSC
for well over a decade. We did run cfengine 2, but just the agent,
in the same mode as cfengine 1. So I'm not a total newbie user.
----
Here's some examples and commentary (I've edited out some irrelevant
parts to save space):
* The first section, after an introductory sentence, starts talking about
how cf3 differs from cf2. Then some description, and then another
paragraph how about how cf3 is different. Then section 1.1 is entirely
about how cf3 differs from cf2.
Now those aren't exactly "go read cf2 manuals" but the reader starts to with
the impression that the documentation is really for the cf2 user who wants
to upgrade.
* Section 1.3, the second sentence starts talking about differences. Then
there's this:
The environment variable CFINPUTS still overrides this
default location, as before, but in its absence or when
called from the scheduler, this becomes the location of
trusted files.
The use of the word "still" implies that one was supposed to know
this already.
Unlike cfengine 2, cfengine 3 does not recognize the CFINPUTS
environment variable.
And this completely conflicts with the previous statement. Does CFINPUTS
still do what it did, or is it not recognized?
* then we quickly come to section 1.7, Upgrading to cfengine 3.
* section 4.2, the working bundle example is for converting cfengine 2 to
cfengine 3! A working bundle example for a new installation would be
much more newcomer oriented.
* Section 5.3:
5.4.3 histograms
Synopsis: true/false store signal histogram data
<snip>
Notes:
This is like the ‘-H’ option to cfenvd in cfengine 2. It
causes cfengine to learn the conformally transformed
distributions of fluctuations about the mean
This is even worse than just referring to cf2 -- there's no documentation
in the cf2 reference to the "-H" option to cfenvd. In fact, it took
me some time to figure out what cfenvd actually *does,* because there's
no explanation of it in the cf2 docs except that it's for "anomaly detection."
I had to google cfenvd to get a useful description.
The explanation provided after that cf2 reference is pretty useless
-- fluctuations about the mean of *what*?!?!
* Section 7.3
File copying
One of the first things users of cfengine 2 will notice is
that copying is now `backwards'. Instead of the default
object being source and the option being the destination,
in cfengine 3 the destination is paramount and the source
is an option. This is because the model of voluntary
cooperation tells us that it is the object that is changed
which is the agent making the promise. One cannot force
change onto a destination with cfengine, one can only invite
change from a source.
So if I'm not a user of cfengine 2, what am I supposed to understand
from this? I might think the paragraph does't even apply to me.
* Section 7.12
Storage promises refer to disks and filesystem properties.
<snip>
In cfengine 2, storage promises were divided into disks or
required, and misc_mounts types. The old mount-models for
binary and home servers has been deprecated and removed
from cfengine 3. Users who use these models can reconstruct
them from the low-level tools.
This is all the text from this section, the rest is examples. Note that
the only really descriptive part of this is about how it differs from cf2.
As a newcomver, I feel that I have to go look at cf2 to see what it means.
> It will help when the website is reorganized. Obviously there is more
> documentation for cfengine 2 at present.
>
> > I can find some particular examples, but it will take me some time
> > to come up with them as I have me head buried just in dealing with
> > cf2. But try going through the docs imagining that you are totally
> > new to it, and don't have a copy of the cf2 docs.
>
> There is no tutorial yet, for which I apologize. On the other hand,
> the docs we have are better than most I have seen for other programs.
>
> Everything is improving all the time.