[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