On Sat, Jul 27, 2013 at 02:45:15PM -0700, Selma Leathem wrote:
What specific issues did you have with the documentation please?
Hi Selma,
I'm glad that you want to work through this with us. I'm posting these
comments to the pspp-dev mailing list so that the other developers
get the benefit of the discussion too. I hope they will have something
to say.
Here are some of the issues that I noticed in the gui.texi chapter:
1. It does have some very long lines. This doesn't make any difference
to the finished product of course, but does make it difficult to read
and edit. In general, we limit our lines to 80 characters or so. Also, in
Texinfo I find it convenient to
start each sentance on a new line.
This way they are easy to cut and paste.
2. The use of English needs attention:
There are a number of places where there are sentances without verbs.
For example: "Central to PSPP, launches when you start a session."
Similarly there are nouns without articles. For example:
"Data view shows the numerical ..." (should be "The data view shows ...")
I don't wish to appear a linguistic pedant, but I do believe that
correct grammar avoids confusion in a manual.
3. There are a lot of uses of @table when there is no tabular material - I think
these should be @itemize or @enumerate.
4. I noticed a few places where markup seems to be missing. For example, there is
an instance of
cindex frequencies
(the @ is missing which results in a verbatim "cindex frequencies" in the output).
5. I noticed that in some places the text
uses the spelling "dialog box" and
in others "dialogue box". We ought to be consistent. I recommend the
former spelling in this case.
6. There are a lot of lists of text written in the imperitive form. For example:
@table @asis
@item Click a cell in the @button{Values}(@pxref{Language,,Attributes}) column.
@item Click the gray box that appears inside the cell to bring up the @button{Value Labels dialogue} box.
@item Enter the @button{Value label}.
@item Click the @button{Add} button.
@item Repeat to add other labels, if necessary.
@item Press OK.
@end table
There is nothing wrong with this. But there is no explanation of WHY
the user is being told to do this. Under what circumstances would
the user need to do this? What does it achieve? After she clicks OK,
what should happen? In a tutorial it is important to teach the reader
concepts - not
merely to follow lists of instructions.
7. Some of the examples, seem rather strange. For example in the subsection called
Split File, you tell the user to do this:
@item Open the file @file{physiology.sav}.
@item Select @clicksequence{ Data @click{} Split File}.
@item Select the @button{Compare groups}radio button in the pop up window.
@item Click @button{Height in millimeters} to highlight the variable.
This will have the effect of splitting the file by the variable height which
is legal but a VERY wierd thing to do. Splits are normally done on categorical
variables such as SEX or RACE. A person who is just learning pspp may not
fully understand what Split File does and will get very confused. We need to
make sure that our examples are reasonable ones.
8. The text needs to be checked for proper markup. For example, the in the following
text:
Return Van der Waerdens transformation, given by the formula @math{r/(w+1)},
where w is the sum of the case weights and r is the rank, ranging from 1 to w.
the "@math{r/(w+1)}" is correct. But the following references to w and r should
also be enclosed in @math{} otherwise they will display in a different font and
confuse the reader.
Ok Selma, I hope you're not too upset with my criticism of your hard work.
This is just my opinion - I'd be interested to hear what others in the
development team have to say.
I do think however these points must be addressed before we can integrate
the work - especially points 2 and 6 above. I think Ben has given you commit
permission, so you can checkin updates yourself now.
I've also noticed that Ben's buildbot is failing on this branch which is
something I must fix.
--
PGP Public key ID: 1024D/2DE827B3
fingerprint = 8797
A26D 0854 2EAB 0285 A290 8A67 719C 2DE8 27B3
See
http://keys.gnupg.net or any PGP keyserver for public key.