-
Notifications
You must be signed in to change notification settings - Fork 0
Home
Welcome to documentation for the BITS lab.
BITS stands for Building Institutions and Technologies Sustainably.
The goal of our research group is to develop, study, and evaluate the use of technologies that serve the public interest. This includes scientific research as well as civic engagement.
Our research lab runs under a cooperative model. This means that everyone has equal say, and equal responsibilities in maintaining our virtual lab. I don't ask much in the way of commitment, other than you agreeing to follow some of the guidelines below.
Let's be a lab that is committed to doing open science that is in the public interest. Sometimes our research will have direct impacts on people and technologies, and other times our impact will be experienced more indirectly by making our work transparent, reproducible, and ethical.
At a minimum, our commitment to open science means that we have a collective responsibility to make our data, software, and publications as openly accessible as possible. That starts with planning and executing our research.
Unless we agree to an alternative all data, software, and documentation must be kept up to date in a public repository. This allows anyone in the lab to see what research is being done, and helps organize our distributed work. In my own experience, this also helps ensure that we can revisit or restart projects with minimal effort.
Working at a distance is hard. CSCW (computer supported cooperative work) is an entire field of informatics for a reason - the effort needed to effectively organize work and cooperatively produce new knowledge is time consuming and complicated.
These burdens are, however, significantly reduced when we commit to pragmatically documenting our work and communicating in open and transparent ways.
For communication:
- By default use Github issues in your repository to ask questions or solicit feedback. Be sure to tag me if you want a rapid response.
- If you need more immediate help or want to have a real-time discussion (or just goof off) use Riot.im [A privacy preserving slack alternative] - our team has a secure private room you can access here
- If you want to schedule a meeting with me use Calendly. DO NOT HESITATE to schedule a meeting. You, this lab, and our research is my #1 priority.
For organizing research:
I strongly prefer using a collaborative platform like Github to organize virtual work for that reason. Github is far from a perfect platform, and Microsoft (the owner of Github) is far far from being a good company. But, I've yet to find an alternative that meets my own research needs and doesn't require a substantial sacrifice of my time and privacy.
Here are some assumptions I have then about our Lab's organization on Github:
- Every project has a unique repository
- Each repository contains the data, software, and documentation needed to reproduce a research project
- The wiki of each repository hosts meeting agendas, links to external documentation, and serves to organize our collaboration
This repository is a template - any time you begin a new project associated with the lab you can follow the steps that are described in the root readme.md file.
At minimum, please organize your repository in the following ways:
- Folders: Use folders to organize
- Wiki: Use the wiki for documentation or linking to existing documentation that is hosted elsewhere (Google Docs). If you create a Google Doc or Word file - please make sure to either upload a copy to the repository after the project is complete, or transfer ownership to me so we don't lose access.
- Data: All non-sensitive data should be uploaded to the repository in a separate folder
- Software: All software should be version controlled using this repository. Be sure to comment your code, and if you are developing a tool we should discuss implementing continuous integration with Travis.
Human participant data should never be uploaded to a public repository. If you are working on a project that includes human participants (surveys, interviews, ethnographies) we can create a private repository to store documentation, and we will discuss a plan for managing human subject data on a platform other than Github.
We should use an MIT license for every repository that hosts research. If you have a strong preference for another license just let me know - I am not rigid in my opinions about licenses.
Where possible, each repository should also have a Digital Object Identifier (DOI). You can obtain a DOI by archiving a repository on Zenodo, and keeping the archive of this repository up-to-date. This must be done at the conclusion of the project. Follow the archiving directions below for how to obtain a DOI and put the badge into Github.
Filing Issues in a repository is the best way to track open questions and facilitate discussion. When you file an issue, be sure to add a label such as "Help wanted" or "Feedback needed" and tag the corresponding lab member with an @
Milestones and Projects on Github are also a helpful way to organize a discrete set of tasks that need to be completed. The benefits of milestones vs projects are somewhat negligible - but I tend to prefer milestones for tracking something like paper writing or prototyping. You should feel empowered to use these as much or as little as you find them helpful.
If you are working for BITS under a paid position you are required to log weekly hours. This should be done via an issue that you file each Friday - the issue should have the following structure:
- Task performed
- Hours spent on task
- Tasks that were not complete, but planned
- Tasks that are planned for the following week
Add the total number of hours that you spent working that week and place this at the end of your issue. Attach a label hours to your issue and be sure to tag me @nniiicc each week.
For your own sake - I highly recommend time tracking with an application like Toggle. Toggle has integrations with Github, Google Docs, etc. This makes it simple to track where and when you spend time working on tasks. I use Toggle extensively to track my own time and find it holds me accountable each week for what I promise to do and what I actually end up spending my time doing.
When we begin to write up results from a study you should do the following:
- Create a Milestone and assign Issues to that Milestone. The first issue should be the intended outlet and due date for the paper. Note - I have a step-by-step writing schedule for papers that is linked here. Please make a copy of this writing schedule document, link it somewhere in your repository's wiki, and update the schedule regularly.
- All drafts must be started AT LEAST two weeks before they are due.
- In advance of starting a paper please make a point to discuss author order with me and any collaborators. If you want a quick overview on why this is important read this short blog post
In the Github wiki for this repository you should be sure to update the following regularly:
- Meeting agendas - each time we meet you should have developed an agenda for us to discuss and things you want help or need feedback on. Make each new agenda a new page.
- Research materials - at minimum, you should create documentation on any ongoing research documentation (e.g. a protocol, a literature review, etc.) in the wiki.
- Data - for any data that we are collecting you should list this in the documentation wiki somewhere. This can be as simple as a page with some explanatory test, and a list of links that point to other places data are stored. As above, be sure that the repository is PRIVATE if you are linking to sensitive data.
After a project is complete:
- Go through your documentation and make sure that all descriptions and research methods are up to date.
- Go through the data that is hosted on Github or another location, and make sure that the final analysis and cleaned data are accessible
- Crate or Update an Archive on Zenodo
- Deposit data in appropriate repository - this will vary on a project by project basis so be sure to discuss with me where we are archiving your data in advance of ending a project.
- Apply the archive feature in Github to the repository so that other lab members know that this repository is no longer active.
Updating this description of our lab: One simple way to contribute to the lab is to help me improve this description. Add new items, edit the language, and make edits to this wiki page to help our lab improve open science practices.