Re: ODE - requirement for Editors


Gregory Leblanc (gleblanc@cu-portland.edu)
Mon, 10 Jan 2000 09:38:36 -0800


Martin Wheeler wrote:
>
> FYI -- sorry to all those who've already received this n times;
> the ode-discuss list wasn't around when I first posted it.

I think I've only gotten three copies so far, but some of these mailing
lists are a LOT slower than others. I'm only sending this to
"ode-discuss", to reduce the number of copies of this I get.

>
> One point I have not seen discussed (or even mentioned) so far is the
> inevitable necessity of having a team of editors involved in this initiative.
> (All writers can benefit from working with a good editor -- I'm a writer; I
> know.)
> Not only to correct the typos, orthographic errors, dubious grammar and
> semantic ambiguities any writer eventually becomes blind to, but -- far more
> essentially -- to ensure that coherent form and structure are maintained and
> understood by all members of a hugely disparate team, usually working in
> (almost) total isolation from one another.

This is something that I've been working on phrasing half this well for
the LDP. Thanks. There is one more KEY piece to this that's at least
as important as having editors; having what I'm going to call an
"authors guide". This could just as easily be called an "editors
guide", but the idea is to define a clear set of conventions that will
be used for documents, and lays out what that coherent form and
structure are supposed to be. Without this, it's hard to know whether
the documents are actually folling that structure.

>
> It's a QA control no serious writing project can afford to be without --
> when properly applied, the benefits are a massive impact on reader perception
> of professional credibility. (Which, I believe, was your concern in the first
> place in calling for greater co-ordination).
> As a group, we would be foolish to ignore this.
>
> In this particular instance, assigning an (SGML-savvy) editor to each and every
> document in the repository would, I believe, solve a great many problems
> (while causing a few others, I have no doubt). I'm perfectly prepared to take
> on this type of contribution to the initiative; any other takers care to join
> me in an editing team?

I don't claim to be all that SMGL-savvy, but I wrote a 5 level outline
using DocBook SGML using only Norm's book on DocBook. It's not that
hard to pick up, and I could certainly handle the easy SGML stuff.
Count me in on that team (and on the similar team for the LDP if it ever
gets formed a little better).

> To make myself perfectly clear -- I see the writer's job as producing clear,
> unambiguous authoritative text for local document purposes; I see the
> collaborating editor's job as helping the writer ensure that that text
> conforms to the overall structural needs of the [global] documentation
> project. (SGML-based or otherwise.)

Sounds pretty clear to me.

>
> Obviously, if the writer were able to mark up text appropriately, this would
> be a bonus; but I feel we should make provision for coping with cases where
> this is either not the case, or where legacy texts require translation.
> A single editor could probably quite easily cope with marking up and
> maintaining a number of different documents.

Depending on the structure of the "old" document, this can be a
non-trivial task. Just last week I decided to take on the job of
updating the Sun Hardware Reference (SHR). While I'm re-structuring
this document as well as marking it up with DocBook, I expect that it
will take at least a couple of months to complete.

>
> I'm also assuming that we can agree on a single markup format for all master
> documents -- my own suggestion would be SGML [DocBook DTD], as being the most
> appropriate for the purposes of editing / publishing; electronic or
> conventional.

I also feel that SGML DocBook is the most appropraite at this time, and
we should consider a move to XML DocBook once that's available, and has
some good tools for it. Enough ranting for me,
        Greg



This archive was generated by hypermail 2.0b3 on Mon Jan 10 2000 - 12:38:41 EST