db-derby-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From yeradis <yera...@gmail.com>
Subject Re: [WWD] Chap 3 and 4 submitted for review
Date Tue, 28 Mar 2006 12:59:58 GMT
wich one is the meaning of  ----  SNIP  - -----

On 3/27/06, Stanley Bradbury <Stan.Bradbury@gmail.com> wrote:
> Jeff Levitt wrote:
>    ----  SNIP  - -----
> > 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?
> >
> >
> >
> >
> Hi Jeff -
> Thanks for the thoughtful and informative feedback.
> Regarding Line numbers: Unless someone strongly objects I think I will
> change the 'Line' references.  They were meant to be used as section
> titles (hence they are included in the code comments where they need to
> be regardless of the actual line number in the file).  It was easier to
> create titles based on the Line number displayed in my editor than to
> think up  something more descriptive, but it is misleading.  Do you
> think the section titles should be descriptive of the code or would it
> be OK just to use words that have no meaning outside of the being
> referred to in the document (e.g. use color names like:  RED, BLUE, etc.)?
> Regarding more codeblocks: I'm fine with adding more codeblocks.  I was
> trying to keep code duplication to a minimum but will happily add more
> to areas that seem unclear.  Would you suggest the blocks of code you
> think would be most helpful?  The one that pops to mind is the
> SQLExceptionPrint code.
> Regarding the DITA document type.  I think you are correct - I really
> did not consider the document type and still don't understand the
> trade-off between them  but certainly the only 'task' in
> twwdactivity3.dita is the
> writing of it  -   : )   I will let you know if I have any questions
> regarding changing this to a reference type.
> And thanks for raising the issue of level of detail.  Like the inclusion
> of more codeblocks in the document this was a judgment call and I do
> want feedback in that regard.  To answer you question about the audience
> I had envisioned someone with rudimentary programing experience but
> possibly not with JAVA and certainly not with JDBC.  Thus, I annotated
> the purpose of each major code section and construct but did not cover
> the programming details or syntax.  The exception is the JDBC calls for
> which I included copies of code within the document.  Like with the
> codeblocks I am happy to add more detail in describing the code where
> needed.  Please let me know what areas require better coverage.

View raw message