On 3/27/06, Stanley Bradbury <[EMAIL PROTECTED]> 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.
