[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Autogeneration of Images

From: Selma Leathem
Subject: Re: Autogeneration of Images
Date: Sat, 3 Aug 2013 09:03:17 -0700 (PDT)

Hello John,

Thank you for taking the time to criticize. I'll look into rectifying all those issues. I hope you don't mind if I take a couple of weeks over it as my schedule is a bit full next week.



From: John Darrington <address@hidden>
To: Selma Leathem <address@hidden>
Cc: address@hidden
Sent: Sunday, July 28, 2013 12:27 AM
Subject: Re: Autogeneration of Images

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

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 or any PGP keyserver for public key.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]