discuss: Clarifying confusion over editing vs reviewer
Subject:
Re: Clarifying confusion over editing vs reviewer
From:
David Lawyer ####@####.####
Date:
28 May 2002 07:57:57 -0000
Message-Id: <20020528005808.A345@lafn.org>
On Mon, May 20, 2002 at 06:19:07PM -0500, David Merrill wrote:
> On Mon, May 20, 2002 at 02:11:41PM -0400, Tabatha Persad wrote:
> > On Monday 20 May 2002 12:36, Joy Y Goodreau wrote:
> > > I'm not really concerned about what name you give to what me and my
> > > review staff, but I do want it to be clear what the
> > > reviewers/editors do at the LDP.
[snip]
> > > 1. They contact the author and let them know that they will be
> > > working with the document. This includes a request to work in the
> > > source. Most authors have responded favorably that we fix
> > > grammatical errors in the source. It creates less work for them and
> > > they seem to appreciate it.
The method of showing them what needs changing and letting the authors
make the change is better for the authors since they learn by this
experience. Otherwise, they don't improve at all if their work just
gets modified by someone else. But I know that it's easier for both
parties for us to just make changes in the author's work. Do we offer
as an equal alternative, the communicating of the changes needed to the
author and point out that they will learn from this experience?
Another route would be to run wdiff (or the like) on the "before" and
"after" versions and send the author this diff. Use the options with
wdiff that will show up the changes best.
One way to proceed would be to quote all comments/corrections made by
the reviewer with say a > "quote" in col. 1 (like in email only the
inverse). My vim editor will automatically add these > in col. 1 once I
start using them. If there are long sections with no comments, then you
could delete them and substitute [snip]. Then the author makes the
changes to the unquoted parts of the doc and finally removes the
>-quotes with an editing command leaving a finished, corrected doc.
Feedback that shows authors their mistakes (or even better, lets them
easily correct their mistakes) will help make them better authors. This
can be used to attract more authors. We can advertise: "Contribute
documentation to Linux and we will help you improve your writing".
> > > In the instances where source is changing rapidly or they
> > > anticipate making changes within the source before we can get the
> > > revision back to them, we don't work in the source. This is also
> > > an option for authors who do not want us to touch the source. I
> > > will tell you that this has been rare in my experience. The
> > > authors I have dealt with are eager to make the documentation
> > > better and more readable, and if we can save them time by working
> > > in the source, they are fine with it.
But I think that my proposed alternative using quotes (or the like)
would be better for the authors.
> > What about conversion from older formats to DocBook? I'm not trying
> > to stir up a debate but it is my understanding that DB4.1 sgml and
> > 4.1.2 XML are the most recent flavors. Is this something that is
> > being done in the same manner as above? I have noticed some
> > conversions mentioned in updates. Just curious.
>
> Conversions are a Good Thing.
A problem with this is that we don't have a converter
docbook-to-linuxdoc. So if someone else that takes over the doc wants
it in LinuxDoc, it's not easy to do it. Thus I think that conversions
may be a bad thing.
> The general sentiment here, with a few dissenters such as David
> Lawyer, is in favor of DocBook. So asking an author to consider
> converting is okay. But we can not press the issue. If they like
> something else, such as LinuxDoc, then so be it.
I think you need to ask them to look at DocBook and LinuxDoc source
first before deciding. If they do, I think most of them will opt for
LinuxDoc (unless they already know DocBook).
>
> We have some wonderful authors, who do most of what makes the LDP as
> good as it is. And they appreciate help to make their documents even
> better.
Also, we have some volunteers that deserve a lot of credit too.
Especially David Merrill, Joy Goodreau, and Greg Ferguson.
David Lawyer
