On Wed, Sep 24, 2014 at 5:23 AM, Jonathan Gregory <[email protected] > 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 [email protected]
_______________________________________________ CF-metadata mailing list [email protected] http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata
