On Wed, Sep 24, 2014 at 5:23 AM, Jonathan Gregory <j.m.gregory at reading.ac.uk
> wrote:
> If a different format would be better for generating the final documents
> in various forms, and is easy to work with, it is worth considering, but
> ...
>
I don't know what tools are being used to manage the DocBook source, so I
can't comment on that, but what I'm suggesting is that the XML is a poor
format for the type of collaborative document editing being proposed -- if
we don't want to change that part of the process then selection of the
tools should be entirely up to the folks managing the document. i.e
determine the requirements, then select the tools.
> 1) We manage the development of the CF-2.x.x document in a source code
> > management system, much like a software project
> > 2) ... the whole fork-pull-request thing for updating the document.
>
> I don't think this is appropriate, and I don't think contributors in
> general
> need to edit the document. The convention is a document, not a collection
> of
> source code files.
I think this is where the disconnect is: the convention document is a
"document", sure, but it is built from one or more source files -- this
isn't really different than software.
In theory, the convention is an abstract concept, and the document is
simply a description of that convention. but in practice the Document IS
the convention. So discussion of the convention, and proposals to add to or
alter it, necessarily involve the actual wording of the document. If you
are going to propose a change of wording to the document, then it sure
makes sense to me to propose that change in the document itself. And this
saves transcribing work as well.
And even if I am managing a large document all by myself, I would put it in
git or similar -- much easier to track changes, keep various versions, etc.
In fact, this is a great example of document-like-software -- it has
versions, more than one version may be published at one, it need "bug"
fixes, etc...
(to be fair -- this _could_ be a bit of the hammer-nail thing -- some of us
have found that git and gitHub are powerful collaborative tools, so we want
to use it for everything!)
> The trac tickets are mostly about how and why to modify it,
> illustrated by the proposed change.
Ah -- "illustrated by the proposed change" -- wouldn't it make sense for
that to be illustrated right there in the document? That's what we are
getting at.
> That is different from software, in which
> the modified code speaks for itself (to some extent), and is accompanied by
> much shorter descriptions of how and why it is has been modified.
I think this is a subtle distinction --there are a LOT of small changes to
code that require a lot of discussion and big-=picture thinking -- and
combining issues with pull requests facilites this well.
Also the CF
> doc is a *single* document, so there isn't the need to keep lots of files
> consistent when making updates. It *could* be broken into lots of
> documents,
> but I don't see an advantage in that.
>
I do -- but that depends quite a bit on the system being used to build the
doc -- but no matter, git works on diffs, so changing a small part of one
big file is very similar to changing a part of one file in a collection of
files.
I think that the difficulty in updating the document is not that we have
> inconvenient software for doing and facilitating it. It is the intellectual
> difficulty of working out what the changes should be that makes the process
> slow.
That is the big one, yes, for sure.
On the other hand, there is also the case of simple typo-fixing or slight
clarity enhancements, or addition small examples -- these don't require a
lot of discussion, so facilitating contributions would be a good thing.
> When we have agreed a ticket, enacting it in the doc should be simple.
> That is happpening slowly now, I presume, because of lack of person-time to
> do it, rather than that the software is awkward.
exactly -- if the community can do more of that work, then the person-time
bottlneck is reduced.
there would still be the need for quality-control - someone would have to
> take responsibility for checking that the change was as agreed.
>
yup -- and a system that makes that easy would help that too. See Rich's
example in his note in this thread.
-Chris
--
Christopher Barker, Ph.D.
Oceanographer
Emergency Response Division
NOAA/NOS/OR&R (206) 526-6959 voice
7600 Sand Point Way NE (206) 526-6329 fax
Seattle, WA 98115 (206) 526-6317 main reception
Chris.Barker at noaa.gov
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.cgd.ucar.edu/pipermail/cf-metadata/attachments/20140924/cc34fb44/attachment-0001.html>
Received on Wed Sep 24 2014 - 10:08:19 BST
