db-derby-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Levitt <de...@mylevita.com>
Subject Re: [WWD] Chap 3 and 4 submitted for review
Date Fri, 24 Mar 2006 03:45:46 GMT


--- Susan Cline <home4slc@pacbell.net> wrote:

> --- Stanley Bradbury <Stan.Bradbury@gmail.com>
> wrote:
> 
> > I've submitted Chapters 1 and 2 of the Work With
> Derby [WWD] document 
> > for feedback.
> > The latest revision of Working With Derby has been
> posted to Jira.  It 
> > can be downloaded using:
> > 
> >
>
http://issues.apache.org/jira/secure/attachment/12324531/WWDpdfNjava0323.zip
> > 
> > This contains the newly completed chapters 3 and
> 4.  Please focus first 
> > on the initial review of these chapters.  The PDF
> file and related JAVA 
> > code are contained in the file: 
> WWDpdfNjava0323.zip
> 
> [ snip ]
> 
> I unzipped the file and looked at the PDF, but I do
> not see a chapter 4.  I see an Intro,
> Activity 1, Activity 2 and Activity 3.  Do chapters
> 3 and 4 correspond to Activity 2 and Activity
> 3?
> 
> I like the Activity 3 example.  One suggestion would
> be is to check the command line parameter
> to make sure it is not over 32 characters.  I "made
> a wish" for something that was over
> 32 characters and got a stack trace that was not too
> user friendly.
> 
> It might be nice for new derby users (and if they
> happened to be new to Java too) to
> get a usage message instead of a stack trace if they
> made this same error.
> 
> Thanks,
> 
> Susan

Once again, great writing Stan!

I have several fundamental problems with the format of
the twwdactivity3.dita topic that describes the
program code.

1.  The first is the line numbers problem.  I know it
seems good to give specific line numbers, but one
change to the code throws off the line numbers in the
entire program file, as well as the references to them
in the doc.  This problem is the same problem Derby
has in the doc with referencing page numbers in the
PDF, and that is why it isnt done at all.  Page
numbers change, and it is too hard to search for all
of the references to them.  It is better to have links
that dynamically change.  For this specific problem, I
recommend we remove references to line numbers, and
also remove the Line numbers in the comments in the
code.  We can then simply reference the title of the
specific code section used in the comment.  

2.  This problem is sort of related to the previous
one.  I think we need to have more codeblocks in the
doc.  Instead of saying "The next line does this, and
then the program does this and that etc.", it should
be more specific.  There are some places where this is
done, but others where it isnt done enough. 
Basically, I think we should say "The code does
something: <codeblock> Code lifted directly from the
program and pasted here</codeblock>  Then the code
checks for blah: <another codeblock> etc. 
Showing specific lines in the doc helps the user more
directly.

3.  This topic is created as a task, but I dont think
it is a task,  I've been trying to think of what it
would be (reference or concept), and I think I have
settled on it being a reference topic.  A task would
define something the user would DO, ie. Do this, then
do this, etc.  But we are really just describing code
here, we arent telling the user to do anything.  Thus,
it should not be a task topic.  I can help you with
rewriting this if you'd like the help, but either way
I think it needs to be changed, because I think it
will be more understandable as a reference topic.  So
it should be rwwdactivity3.dita, and of course you
should modify the reference to it in the ditamap file.

I think this file needs a little bit more work.  I can
help you with all this.  I can even do all this work,
I just wanted to see what other people think before 
working on it.  I also would question how much of this
is useful to the user.  Fundamentally, we are
describing what the code does in this program, but
what will the audience be like?  Are they beginners
who have never seen code before?  If so, then this
might be too complex for them.  But if they are
advanced, then maybe describing DO and WHILE loops is
a little too basic for them.  So the conclusion is
that this topic does not talk to either a beginner or
an expert; in other words, there is no one that this
speaks to.  I think the answer is that it is a
document for users who are more advanced, and so I
think we could skip some of the more basic
descriptions of what the code is doing.  We should
focus more on the Derby-specific steps (connecting,
inserting, shutting down, etc.), rather than non-Derby
specific stuff (like WHILE and DO loops, printing
output, etc.)  Obviously this is a topic for
discussion.  What do you all think?  


Mime
View raw message