[Babase] Documentation editing, Susan's first pass
Susan Alberts
babase@www.eco.princeton.edu
Thu, 19 May 2005 10:00:43 -0400
Dear all,
i've gone through the documentation that Anne has converted. It is
looking really good. I can now see why Karl wanted us to go with
Docbook, it is very flexible. However, I found it awkward to work on
the "raw" file with all the docbook formatting, and I think if we do
much more of that we will need a bit of a tutorial, although it
shouldn't be hard. I don't clearly understand how my changes will be
incorporated with the chanages that Anne made yesterday, but I would
really like it if someone confirmed that that incorporation has
happened. Anne, let me know if you can "see" my changes.
I had already started on the document with the long lines so i
continued with that. Leah will put it back on the server today. I
found that, in fact, there were three sorts of lines in it, (1) lines
with no wrap that were very long, (2) lines that wrapped but I
couldn't see what was controlling that, and (3) lines that were
wrapped because they were interupted by paragraph marks. I think many
of the ones in set (3) were errors -- ie the lines should NOT be
interupted by paragraph marks, but i don't know if that makes a
difference.
In making changes to the document I opted for being conservative in
several ways -- especially in adding information to table
descriptions. We may end up with some repetition and redundancy for
this reason -- ie information appearing in more than one place, but
this seemed better than the opposite error.
One general overall remaining issue with the document is that the
organization and formatting is not yet complete -- for instance, the
sections are not all flagged in the table of contents and they don't
have outline letters and numbers. in many places in the document we
refer to "section VII.B" or whatever, so this needs to be fixed
eventually.
Another general overall remaining issue is simply that a number of
tables are not yet described.
I've done three sets of things to it.
1. Made some changes directly to the text. These were fixes of typos
or changes that Karl and I discussed.
2. Inserted a number of comments about things that need to be
attended to or suggestions for changes.
3. Added double asterisks (**) in a number of places where Karl needs
to look at it and see what changes need to be made. In some cases
I've just flagged a word (particularly FoxPro) that indicates a place
that needs to be updated to reflect our new system. In other cases
i've made notes to karl that involve questions for him to answer.
I guess that's it for now. Let me know if there is feedback.
Susan
--
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Susan Alberts, Associate Professor
Department of Biology, Duke University, Box 90338, Durham NC 27708
phone 919-660-7272 fax 919-660-7293