[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [xmile] version control for Spec documents
Hi Bob,Thanks for the reply. I think that makes sense - my concern mostly resided in how individuals collaborating on a piece were interacting. Leaving that to people working together on a piece simplifies things, but does require that the person holding the pen on the section do some additional work to synchronize between piece-collaborators and the rest of the TC.Lets go with what you suggest, unless other people have objections or concerns.yours,BobbyOn Tue, Sep 3, 2013 at 10:30 AM, Bob Eberlein <email@example.com> wrote:
My belief, and perhaps others do not agree, is that we can subdivide our final document into a relatively small number of pieces and assign authorship control of those pieces to one or two individuals at a time (essentially between meetings). Currently we have identified 5 pieces, and that might grow to 10 or 12, but I don't see it getting bigger than 20.
With that approach there is never any issue of merging content, since the editors of each piece are clearly identified. If two people are working together on a piece then they can use whatever form they want to do so (track changes, google docs...). That editing is not being presented to the committee as a whole and need not be kept with the documentation records for the committee. When they finish editing to the point of wanting to share, that document then needs to be uploaded to oasis.
I think this approach is both simple and practical. Allowing more people to change more things is necessary in code, but could be problematic in writing a spec. It seems more sensible to communicate how and why things need changing to the people holding the pen on the section needing change. If they disagree, or have a different idea, it could save a lot of rework and prevent unpleasant surprises.
On 9/3/2013 10:13 AM, Bobby Powers wrote:
Sorry, I didn't fully finish my thoughts in that last email. I am suggesting we worry about the major content of the spec now by using something like markdown or google docs (a lot of this content is currently contained in Karim's v4 documents, but as per our last call we have a number of areas we would like to work on) that is easy to collaborate in, and once we have the majority of the content written in a way we're happy with, worry about moving it into a format suitable for generating the required HTML & PDF outputs.
I explicitly worry that the overhead involved with managing 10 people's changes to a set of Word documents will discourage collaboration and progress. With that said, if that is the format most people are comfortable with I am happy to quiet down and defer to the group on this subject - I just want to effectively communicate my concerns before doing so.
On Tue, Sep 3, 2013 at 10:00 AM, Bobby Powers <firstname.lastname@example.org> wrote:
I think there has been a little confusion - my understanding of Billy's email was that he was suggesting making the final spec available in PDF - not collaborating on the content in PDF form.
I think there are 2 separate issues here
1 - collaborating on the content of the spec2 - formatting and providing the finished spec (and potentially draft forms) in formats required by OASIS
I had originally suggested Markdown in my email to Will because it is about as simple a format as possible, and there are lots of tools to generate PDF, Word and DocBook documents from Markdown source . It would let us individually edit files and then merge changes in a straightforward manner, and is readable in a simple text editor:
Similarly, Google Docs allows multiple people to edit the same document - since it is server-based, the base document never diverges and explicit merges aren't needed.
Merging Word documents is challenging and does not integrate into version control tools like Subversion or git - it would require additional work from us to avoid having to do merges, or manually merge documents when the need arises. It is manageable, but worth explicitly mentioning
I hope this helps move us towards a shared understanding of the discussion - please correct any mistakes I have above :)
1 - http://johnmacfarlane.net/pandoc/ for example
On Tue, Sep 3, 2013 at 9:45 AM, Steven Adler <email@example.com> wrote:
PDF is not editable. We have to publish in forms that can be edited, copied, derived, etc.
From: Bobby Powers <firstname.lastname@example.org> To: Robin Cover <email@example.com> Cc: Billy Schoenberg <firstname.lastname@example.org>, Karim Chichakly <email@example.com>, firstname.lastname@example.org Date: 09/03/2013 09:41 AM Subject: Re: [xmile] version control for Spec documents
Can you explain what you mean by editable source? All of the options we have been mentioning have been editable-source formats matched with potentially a version control system (which is tangental to the editable source requirement). The only thing I can think of that might conflict is Google Docs, where we would have to export from Google Docs to get the source (I think).
Did you see specific problems with what we were discussing, or were you just reminding us about the OASIS requirements?
On Tue, Sep 3, 2013 at 9:00 AM, Robin Cover <email@example.com> wrote:
About GitHub, spec formats, word processor files, etc...
I see that the TC members are sorting out options for version control in connection
with a partitioned spec (assignment of parts for different authors/editors).
You might want to consider the use of DocBook (XML) based upon the package
of XSLT scripts prepared by Ken Holman for the publication process. Or.. you
can roll your own. We (OASIS Staff) encourage you to use whatever tools
are best for your productivity, but we try to promote the use of tools that match
the vintage-1993 origins of the organization = structured information based upon
separation of concerns (content/structure versus display/presentation) qua SGML/XML.
As to the formats, and "final" publication formats, I spotted this:
"... our final product should be distributed in PDF form as opposed to Word..."
Reminder: OASIS requires editable source as well as (X)HTML and PDF:
Why? for many reasons, but we allow derivative works, and for use of
a reliable source as a basis for a derivative work, the editable source
is obviously the best. Trying to create (secondary) "editable" source from
PDF is not a good idea.
On Tue, Sep 3, 2013 at 7:41 AM, Billy Schoenberg <firstname.lastname@example.org> wrote:
Merges are the main reason why something like .doc files are not great with something like github. Because the format is binary and git does textual merges obviously a merge will never be successful.
I feel that our final product should be distributed in PDF form as opposed to Word because of the wider availability and the high availability of free viewers/editors.
With that said since we need to use the OASIS template we should see if the word template opens nicely in google docs. If so I think that would probably be the best place for us to do our work as it would handle for us the version control fully (including merges) and the styles/templates required by OASIS.
On Mon, Sep 2, 2013 at 4:11 PM, Karim Chichakly <email@example.com> wrote:
Thanks for your suggestions. I will echo Bob's sentiments since:
a) Our final specification is supposed to be in something like Word (I also prefer Word over the other choices), and
b) We should be starting this effort from the OASIS Word Template, to avoid reformatting later. I will have to get hold of that and pass around.
On Mon, Sep 2, 2013 at 2:50 PM, Bob Eberlein <firstname.lastname@example.org> wrote:
My preference on this would be able to work in Word. Splitting the document up into the appropriate pieces will take a bit of work, but that structure won't change often. I also think it would be useful to hand the pen off on the different pieces pretty explicitly outside the context of the version control system (basically during our meetings).
Is there any reason not to use github for managing .doc files? Or phrased another way is there any reason not to use .doc files on github?
On 9/1/2013 9:46 PM, Will Glass-Husain wrote:
Hope everyone (in the US) is enjoying their Labor Day weekend.
In the last committee meeting, we split up the document writing into various sections.
I'd like to propose we use version control while writing the spec documents. This helps collaboration by seeing changes added over time by various members of the group and make it easier to provide comments.
I suggest one of the following two options.
The simplest (for most people) is to use Google Docs. You can edit the document using a Microsoft Word like approach (WYSIWYG). The document lives on line, formatted. Each time it is changed and saved a version is stored. This allows us to review the changes to the doc over time. Final version of the doc may be downloaded as MS Word and if necessary additional formatting applied. A benefit of this approach would be ease of use for those familiar with Microsoft Word and other word processors. A negative is that everything needs to be edited online.
A second approach would be to use plain text documents formatted with Markdown, and to use Github as version control. The more technical members of the committee may prefer this. Bobby powers (see appendix to my email) has assembled several examples of how this would work. This would be a good approach if everyone writing was comfortable with git and version control. Github has something called a "pull request" which makes it easy to comment on specific parts of a document. The final document could be converted to PDF or HTML.
Once we choose an approach, I can set everything up, with Google Docs or Github. We should probably choose one approach for the entire document.
---------- Forwarded message ----------
From: Bobby Powers <email@example.com>
Date: Thu, Aug 29, 2013 at 6:38 PM
Subject: markdown example
Here is the repo:
Here is a page with some of the things we want (code blocks of XML, inline tags, and lists):
And here is the source for that page:
This is a pull request which can be used to manage changes:
And here is the markdown syntax:
I didn't do a GDoc example - I think that is more self explanatory (Word on a web page).
OASIS, Director of Information Services
Editor, Cover Pages and XML Daily Newslink
Staff bio: http://www.oasis-open.org/people/staff/robin-cover
Cover Pages: http://xml.coverpages.org/
Tel: +1 972-296-1783
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]