Suggestion for alternative IEOS document collaboration process

[tmillross]

Morning all,
When we view the in-progress Manifesto as described in #7 , we're greeted by a page of multi-coloured text, highlighted comments, text-strikethroughs, paragraph markers, and comments which extend past the final page! Might an alternative collaborative writing approach be useful for our requirements? I'd like to make a suggestion regarding the document writing process used by the group, to collectively draft documents or similar artefacts in the future.
We could use a similar development model to those we use for our codebases. The Open Science Github root directory or a sub-folder would include a text document which adheres to a standard we agree to. For instance a Markdown .md file, to handle our (fairly minimal) formatting requirements. Brief contributing guidelines would be drafted to describe what's expected from contributors.
Those that are comfortable editing the repository files on their local machine could use their typical development workflow. Those that prefer a web-based GUI could rather use the friendly and accessible Github file editor, which is almost as easy as editing a Google doc, but has the benefits of commit messages etc.
As I'm preaching to the choir here, I suspect most of you can recognise the advantages this may bring over the Google-docs approach! Please comment also if that's not the case, or if you'd like to discuss and evaluate more comprehensively the pros and cons of collaboration alternatives.
If this idea is supported, and if the Manifesto is not yet at completion, we could implement the process without too much effort for even for this current document. We'd lose the editing history that Google maintains. But would gain improved traceability, discussion, and efficiency improvements for any future edits.
I finish by quoting this evangelical blog post and look forward to hearing your thoughts.

These practices, layered on a common understanding that all shared artifacts ought to be versioned and all changes carefully controlled and documented, should never have been restricted to software development. We're all doing distributed work that must be coordinated with care, attention to detail, and team awareness. Git made that possible for programmers. GitHub is making it possible for the rest of us.

[nheeren]

Hi @tmillross. I think you have a good point and I it would be nice to identify and recommend a workflow for the future. I am a huge fan of markdown and almost exclusively use it for my own writing these days. Nevertheless, there are a number of shortcomings when it comes to collaborative writing and I am not sure how to overcome those.

• For instance, we often need to discuss specific sections or even the choice of an individual word. Having such a discussion in commit messages in a, say, 20-page document seems cumbersome to me.
• Another thing that often bothers me with GitHub in general is that it may make it difficult to include everybody in the workflow. For instance, I know professors that refuse to work on anything else than MS Word documents. While such people may be convinced to give Google Docs a try, I don't see them fiddling with commits, etc.

For the document in question, i.e. "the manifesto", I would strongly vote for not migrating now, as we are already struggling with the workflow and I intend to finalise the document this week.

[ricklupton]

I agree with this in principle, but also that it's too late to be worth it for the current document.

For instance, we often need to discuss specific sections or even the choice of an individual word. Having such a discussion in commit messages in a, say, 20-page document seems cumbersome to me.

I think GitHub makes it quite easy to have discussions about particular lines of code/text within a pull request, as well as conversation about the whole set of changes -- I don't think it would have to take place in commit messages.

Another thing that often bothers me with GitHub in general is that it may make it difficult to include everybody in the workflow.

I agree this is important and worth thinking about. But is this kind of professor going to be engaging directly in collaborative editing in Google Docs anyway? If we wanted to circulate a draft to people for feedback, it would be easy enough to copy & paste into a Word document or Google Doc if that made it easier for people to contribute. Might be worth it if it does actually make it easier to collaborate for the main group of people working on the document in GitHub.

Maybe we should try it next time we have something to write...

[ricklupton]

I intend to finalise the document this week.

@nheeren let me know if you want any help

[tmillross]

Understood regarding the current manifesto, it doesn't make sense to change midway. And thanks for the support on the idea for next time. Inevitably there'll soon be another document to co-author within IEOS, hopefully the initiating author for that one has spotted this issue and is willing to try out something new 👍
Good luck with the comment-review-formatting-finalising task!