Make text accessible to yourself and others now and in the future
Reduce chances of work being lost or people overwriting each other’s work.
Make it easy to track and combine contributions from multiple collaborators.
Avoid duplication and manual entry of information,
particularly in constructing bibliographies, tables of contents, and lists
Make it easy to regenerate the final shared form (e.g., the PDF),
and to tell if the PDF in hand is up to date.
Make it easy to share the final version with collaborators and submit it to journals
We recommend against traditional desktop tools like LibreOffice and Microsoft Word
because they make collaboration difficult:
six people mailing each other copies of a paper with “Track Changes” enabled
is a sure way to lose work (and time).
The nerd alternative is:
Manuscripts are written in a plain text format such as LaTeX or Markdown that plays nicely with version control
Tools needed to compile manuscripts are managed just like tools used to do simulation or analysis
But as Stephen Turner said,
“…try to explain the notion of compiling a document to an overworked physician you collaborate with.
Oh, but before that, you have to explain the difference between plain text and word processing.
And text editors.
And Markdown/LaTeX compilers.
And GitHub. Etc.
Meanwhile he/she is getting paged from the OR…”
We therefore also support an alternative to text + version control:
Manuscripts are written using Google Docs or some other online tools with rich formatting and change tracking
A short text file is added to the doc directory with metadata about each online manuscript
Just as the data directory might contain links rather than actual data
The manuscript is downloaded and saved in doc in an editable form (e.g., .docx or .odt) after major changes
The justification is:
If the document lives online (Google Docs or Authorea),
then everyone’s changes are in one place,
and hence don’t need to be merged manually.
If the document lives in a version control system (GitHub),
it provides good support for finding and merging differences resulting from concurrent changes.
Stage 2: Desired Results
How do I make my work more accessible to others in my field?
How do I collaborate with colleagues while writing?
How do publishers and researchers keep track of who published what?
How can open access publication and open review be implemented?
What are their pros and cons?
…write and review research-related documents in Google Docs
…write research-related documents in Markdown
…review documents on GitHub
…turn Markdown into PDF or HTML using Pandoc
…publish Markdown using GitHub Pages and Jekyll
…comment on a web page using hypothes.is
…add my ORCID to electronic manuscripts
…get a DOI for a publication from Zenodo
…the difference between WYSIWYG formats and markup