Why host a docathon?
Learning how to code, how to analyze data, how to do your work openly, and how to collaborate with others requires an incredible amount of self determination. While classes and our colleagues can teach us quite a lot about best practices in programming and the potential that exists in our respective computer languages, we must often rely on ourselves to learn about the tools at our disposal.
For this purpose, the first point-of-contact many of us have with a package is its documentation. This can serve as simple "how-to" guide for how a package works and the API that is reveals to the user. It can also serve as a "best-practices" exemplar for how others "should" use a package. Sometimes it can even be an introduction to an entire field.
Documentation is important because it's one of the first connections between the human world and the machine world. It helps us effectively translate our concepts and ideas into the languages that we use to control machines. Or, it can be a confusing mess, and hurt more than it helps.
We believe that we can do better with documentation. While there are a few shining jewels of well-documented projects, the vast majority deserve to be improved. However, improving documentation is very different from writing better code. It requires the developer to intuitively describe their package and the ways that one might use it, a difficult feat for someone who is mired in the details of their package.
This is where the docathon comes in - we hope to be a source of community and inspiration for writing better, human-centric documentation. We exist both as a place learn how to connect our computer code with our users, as well as a place to push one another to improve documentation across the open-source ecosystem.
The first docathon will be held in early 2017, as a week long hacking session focused around improving our docs and creating tools to make documenation more effective. It will be focused at UC Berkeley, but we invite individuals from all over the world to join in for this week of intensive improvements to documentation. Whether it be offering a package that could use some help from the community, or simply taking a few hours to work on your own package's tutorials and docstrings, we welcome any and all contributions.
Stay tuned in the coming weeks for more information about the first docathon, and how you can help out. We look forward to documenting with you all soon!