We are trying to write collaboratively an article with rules/guidelines on how to organise unseminars/unconferences in bioinformatics:
- Background on where the idea for the article came from
- Where we will try and publish the article
- Info on the technology we will use to write the article together
- How (technically) to start writing the article with us
- Which files, and what kind of content, to contribute
- Getting help to contribute yourself to the article
- 1 Background
- 2 Where to publish the article
- 3 Technology
- 4 How to contribute technically to the article
- 4.1 Send us your public SSH key (and generate one if you don't have one already
- 4.2 Install GIT
- 4.3 Check out the most recent version of the text
- 4.4 Edit the files
- 4.5 Stage the files you've edited
- 4.6 Commit your change locally
- 4.7 Push my committed changes to the repo
- 4.8 Get most recent version of a previously-cloned repository
- 4.9 Dealing with conflicts
- 5 What to edit and how
- 6 Getting help
The idea for this came from the ISMB/ECCB 2013 conference in Berlin, July 2013, where we organised a Birds of a Feather session on organising unconferences and unseminars in bioinformatics.
The session was fun, giving us a chance to introduce the idea of un* events to people, while meeting others from across the world who also enjoy these kinds of events; we set up a small WordPress site to describe and record what we got up to at the meeting.
We want to write the article collaboratively with many different people, in this way hopefully making the rules we come up with more generally relevant and applicable.
We will also take the chance to try and find together a hashtag we think could be useful to refer to us events in Tweets
Where to publish the article
We will try and write together an article for the PLoS Computational Biology "Ten Simple Rules" collection. With this we aim to raise awareness of what meeting formats of this kind have to offer, and to help make it easier for others who might want to organise their own by sharing our experience with them.
If possible, we will try and list all contributors to the text of the article as authors, in the order in which they contribute to the text, however we can't yet be sure this will be possible
We also want to use the article as an opportunity to learn about working collaboratively using version control tools, in particular git; this is clearly a tool that is useful for many of us, when it comes to keeping track of and collaborating with others to produce documents, including code, and we know that many of us would like to get more practice using it in a collaborative context.
We will also use the opportunity to get experience using markdown as an efficient and easily-convertable way of preparing text documents.
- Introduction to markdown
- markdown syntax explained
- pages for pandoc, a command-line tool for converting markdown into a range of different formats e.g. html, docx, tex
- [http://aidanbudd.wordpress.com/2013/08/15/markdown-and-pandoc/ quick intro to why/how markdown can be used with pandoc
How to contribute technically to the article
Send us your public SSH key (and generate one if you don't have one already
Firstly, send Holger (one of) your public SSH keys, and your name, (changing the email address to your email address) so that he can register you as a user in the git repository we use to write the article.
I've no experience doing this in Windows, but this page looks a useful place to start.
This is the "how to" I used to do this on my Mac
- git for Windows: http://www.git-scm.com/download/win
- git for Mac: http://www.git-scm.com/download/mac
There's also a nice graphical frontend for git called SourceTree that you might want to use instead of the commandline:
- Windows/Mac: http://www.sourcetreeapp.com/download/
Check out the most recent version of the text
Once your SSH key has been added (which might take a day or two), you can get your hands on the repo, copy and paste this:
git clone firstname.lastname@example.org:dinkel/plos10rules
Once you've checked out the repository, you should be able to see 'usingGitToContributeToTenRulesUnseminarsPLoSArticle' in your home directory. If you have downloaded GITHUB, you can go to the bottom left hand corner, click on add local repository and then add it from your directory.
Please note that the repo is not public,and you will not be able to find it if you do a search under repositories.
Edit the files
Stage the files you've edited
git add theTenSimpleRulesAddYourIdeasToThisDocument.txt
Commit your change locally
Push my committed changes to the repo
Get most recent version of a previously-cloned repository
Dealing with conflicts
It is almost inevitable that, with multiple people editing these files at the same time, conflicts will arise i.e. one of us will make changes to a file that cannot be reconciled with changes made by someone else.
In this case, try using git like this, or with another merge conflict resolving tool
git mergetool -t opendiff
if this doesn't work, then that's not so surprising either, it can take a bit of fiddling to set up your system to start a conflict-merging tool.
We have put more detailed instructions on this in the usingGitToContributeToTenRulesUnseminarsPLoSArticle.txt file in the git repo associated with the article, together with another file for you to practice your merging and conflicting on i.e. conflicts_sandbox.txt
What to edit and how
There are several files in the repository.
We have decided to organise collecting contributions to the manuscript in the way described below.
Please keep an eye on the top of this page (or read the mails we send to you about this) so that you know what kinds of contribution we currently need from you!
The Ten Simple Rules
1. Collect a list of possible rules
- Edit theTenSimpleRulesAddYourIdeasToThisDocument.txt by adding any rules that you think could be included in the manuscript, but which are not yet in the document
- If you want, add a short text below a new rule, to explain in a bit more detail what you mean by it
- You can also add your name to any rules you contribute.
- We aim to do this by the end of August, but might take longer
2. Remove redundancy from set of selected rules
- Several of us in Heidelberg will work through the list of rules proposed, removing redundancy by merging similar rules, and adjusting their text as we need to so that we feel we understand the "final" list, and have captured the thoughts/ideas that were proposed
3. Vote to decide the "final" set of 10 rules
- We'll do this by asking you to edit the full list to indicate which rules you think most important to include in the final list of "10" we write about by adding your name to maximally 10 of the rules in the theTenSimpleRulesAddYourIdeasToThisDocument.txt file
- Please don't do this until we indicate we're ready for this!
- After a set date, we will count up the number of votes for each rule, and prepare a document with the top ten listed in it. In the case of a tie, a group of us in Heidelberg will decide how to resolve this
4. Write the more detailed description for each rule together collaboratively
- We will let you know once the final 10 have been chosen, and will then ask you to help us write the short description to go with each of them, with a deadline after which we will take the document as is, polish the text, and prepare a draft to be viewed and hopefully OKed by all contributors
Let us know you've started contributing to the article
We're going to try assigning authorship to the article in the order in which people make their first edit to these documents.
Probably there's some cunning (or not so cunning e.g. just reading something like git log...?!) way of keeping track of this, but we thought it might be even simpler if, after you've made your first contribution to the file theTenSimpleRulesAddYourIdeasToThisDocument.txt you just add your name to the bottom of the list of authors in the file TenSimpleRulesCollaborativeArticleAuthorList.txt
The Hashtag suggestions
Add any ideas you have for possible hashtags to refer to unseminars/unconfernces (maybe hackathons too?) in bioinformatics by adding your suggestions to the list in this file: possibleBioinfUnseminarUnconferenceHashtags.txt
once we have a reasonable list, we'll try and organise a vote to find the ones that are most favoured, as for the manuscript described above
Example of a "Ten Simple Rules..." series from PLoS
Ten Simple Rules for Reproducible Computational Research http://www.ploscompbiol.org/article/info%3Adoi%2F10.1371%2Fjournal.pcbi.1003285
We realise that using these technologies to write the document will make contributing to the document difficult for people with limited experience of this kind of tool; thus, Holger Dinkel has kindly offered to give what help he can on this. You can contact him by mailing him at his work email address, which is made up of his first name, a dot i.e. an "." and then his second name, followed by @embl.de.