OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

xmile message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [xmile] version control for Spec documents

Hi Will,

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?

               Bob Eberlein

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.

Any comments?


---------- Forwarded message ----------
From: Bobby Powers <bpowers@iseesystems.com>
Date: Thu, Aug 29, 2013 at 6:38 PM
Subject: markdown example
To: wglass@forio.com

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).


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]