Docathon

What's a docathon?

It's kind of like a hackathon, but focused on developing material and tools for documentation. Hackers of all skill-levels are welcome. The docathon will be held in late February, 2017, stay tuned for more details on dates. It will hopefully be the first of many docathons to come!

Why a docathon?

Everybody knows how important documentation is. However, as important as it is, we often don't give documentation enough attention. Docstrings are incomplete or missing argument explanations, examples don't compile or reveal outdated APIs, tutorials are often idiosynchratic (or not even there). The docathon is about changing that.

How Do I Join In?

All you need is a project to work on that isn't your regular day job. We recommend you choose something open, perhaps on GitHub or Bitbucket, so that others can see your progress. In the coming weeks we'll send out a formal call for ideas and projects, and you can sign up then either as a project host or as a contributor.

Nov 10, 2016

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!