Docathon

Docathon recap!

2017-03-10T00:00:00-08:00

It's hard to believe but the week has already flown past, and we now live in a new, post-docathon world. Little did we realize the paucity of documentation that we once had, and the cornucopia of new examples, tutorials, and docstrings that now exist in the open-source world. OK maybe that's a little dramatic, but I'm super impressed with all of the great work that people did over the course of this week. Whether it was migrating documentation over to Sphinx, creating beautiful sphinx galleries to show off visualizations, or launching that new project website, I want to thank everybody for pitching in and being part of the first docathon!

Let's take a look at the final rundown of stats...

The final project docboard

First things first, aere's what our activity looked like for the week. I increased the time span beforehand so that we can get a better look at the context for this amount of activity. That's, like, a thousand times more documentation than there was before this week. How awesome is that?

Global Activity

And here's the final project leaderboard:

The winner goes to.............

Pycortex!

And a big thanks to our participants!

We got a lot of great contributions from people that signed up as participants as well. We were a pretty diverse group, spread out across all parts of the world:

And of those users, we had a few very special folks that really knocked it out of the park this week! Here's our user leaderboard:

It looks like r-b-g-b, lmcinnes, and alexhuth nabbed the top spots, but I'd like to think that everybody is a winner at the docathon :)

If you want to continue the party!

If you want to continue connecting with fellow documenters out there, we're going to open up a channel in the Write the Docs slack room. It'll be a great way to connect with the broader documentation community. You can also always shoot us a tweet @docathon, or open an issue on our repo.

Once again - thanks so much for participating in the docathon this year. We hope that you enjoyed it, and that you or your project can be a little bit prouder of your documentation now that it's over. We're excited to do it again soon!

Until then,

The Docathon Team

Docathon Day Four: Galaxy Hub jockeying for first place

2017-03-09T00:00:00-08:00

You know that story about the tortoise and the hare? Where the slow, methodical approach of the tortoise ultimately overcomes the fast but inconsistent progress of the hare? Well there is a little-known second chapter to that story, where the tortoise manages to develop cloaking technology such that it is rendered invisible to the hare. As the hare nears the finish line the tortoise lowers its invisibility shield, revealing that it had actually been cruising along on its own little jetpack the whole time.

Well that's basically what happened today with the docathon. While pycortex was enjoying an early victory, galaxy-hub decided to show up to the stats board (note: this definitely, assuredly, totally obviously did not have anything to do with a bug that I wrote into the stats plotting function).

We've only got one more day of docathoning remaining! Let's see who finishes on top, and who can make the most commits in the final day! I heard there might even be some prizes for the users with the most commits...

Docstars for the day

I'm really impressed that we've got four straight days of documenting under our belts. Who'd have thought you could motivate open-source projects to spend so much time on their docs :)

Global Activity

There are a few new projects that have shown some great progress in the last day!

First of all is the aforementioned galaxy hub, which is an open platform for biomedical computation. Next up is pandas, everybody's favorite data wrangling, munging, and pseudo-databasing tool. Finally we have a newcomer to the open-source world, as diy recently unveiled itself to the world as a package for parallel computing, like a butterfly out of the cocoon.

And let's see what the user board looks like:

OK I'm not even going to mention r-b-g-b, who has apparently done nothing but drink red bull and document code for the last 3 days. For the users who are not superhuman, we should give a shout out to mrzv, ketch, and spopham for giving us a day 4 bump.

One more day to go!!!

I can't believe it's almost over! I'm amazed at all the great improvements that I've seen over the last few days. Let's finish strong with a flurry of commits the likes of which the world has never seen before!

Go forth and document!

The Docathon Team

Docathon Day Three: I'll have what pycortex is having

2017-03-08T00:00:00-08:00

Every civilization has its heroes. Some are soldiers, politicians, teachers, mentors. And some are documentors. Today we celebrate the heroes of documentation (well, of the last 24 hours anyway).

Firstly we celebrate pycortex, which has maintained a documentation streak not seen since the great Steve McDoccerson back in the late 80s. Way to go pycortex!

We also celebrate the unsung heroes. Not because they do not do amazing work, but because they...do not use Github. Sadly our scrapers aren't working with non-github projects, but that hasn't stopped yt from converting all of their documentation to sphinx-gallery during the docathon.

Finally, we celebrate those who are halfway they - AKA, all of you! We're nearing the end of Day 03 of the first docathon, and I'm amazed at what people have put together already. Truly, you are all the heroes that we deserve.

Docstars for the day

We are keeping up the pace! Let's keep it going for two more days!

Global Activity

It almost goes without saying at this point, but pycortex has maintained its superhuman documenting pace. Will they ever slow down?!

We also wanna give a shout out to matplotlib which is making the noble effort to create a sphinx gallery, as well as quanteda which wins the prize for "awesomest documentation in R package so far" Yeah!

And let's not forget about the users that are making all of this possible. I'm beginning to think some of you are gaming the system ;-) but all is fair game in the world of documentation:

Congrats to r-b-g-b, alexhuth, and lmcinnes.

Two more days

Keep up the momentum as we head into the home stretch of the docathon! And don't forget to get those PRs merged sooner than later, so that they show up on the docaboards. Looking forward to finishing strong and seeing what you all come up with!

Until then, I leave you with our new mascot, the true hero of the day:

The Docathon Team

Docathon Day Two Update: Even doccier

2017-03-07T00:00:00-08:00

As the sun goes down on Docathon Day two, we have more great contributions to celebrate! At BIDS, we held a special session of The Hacker Within, teaching attendees how to set up Travis to auto-build their own documentation. But you don't care about this...you want to get to the stats!

Docstars for the day

We got another nice bump in commits for the day, as seen on our global activity board:

Global Activity

And here is the list of projects that upped their documentation game:

Way to go PMagPy, for managing to hit the top three two days running. In addition, we saw two new leaders pop up in pycortex, which creates beautiful javascript maps of brain activity, and HDBSCAN, which is a high-performance implementation of a machine learning method built for scikit-learn. Way to go!

Our user leaderboard saw three new folks at the top today:

Congrats to lmcinnes, staeiou, and another victory lap for willingc.

Quick notes

A few projects have been working on a branch that isn't master for their doc work. If you won't merge this before the end of the week, let us know on slack or via a github issue which branch you're working on. This way we can give you credit as you make new commits!

We'll try to get the youtube video from yesterday's lecture split up and combined with links to repositories of information by sometime tomorrow. In the meantime, I want you all to keep documenting! Do it for the partyparrot!

Until then,

The Docathon Team

The Docathon is One Day Old!

2017-03-06T00:00:00-08:00

The docathon just turned one (day old)! Here's a quick update to congratulate everybody on a great first day.

Updates

We kicked off the week at BIDS by hosting a half-day of Documentation Tutorials. These were live-streamed on youtube for your viewing pleasure!
We also demoed a template repository to help you get sphinx / numpydoc / sphinx-gallery working with your project. Use that along with this guide repository to help you get started!

Check out the docboards!

My favorite thing about today is that you can totally see a bump in the documentation commits for our projects. You can check that out on our global activity board below:

Global Activity

We should also give a shout out to our docstar projects that showed a big bump in activity today. Here's our docboard for project commits:

Three cheers for:

PMagPy, a python project for analyzing paleomagnetic data
cottoncandy, a project for storing and flexibly accessing numpy data on Amazon S3.
Sylius, a platform for e-commerce using PHP

We also got a big bump in commits from individual users! Here's what everybody has been up to:

Let's give a shout out to this day's docstars anwarnunez, willingc, and swanson-hysell.

Keep it going!

We look forward to seeing what comes next tomorrow. The working groups will be holding sessions once again, though we've gotten a lot of great contributions from people all over the country! We're making great progress, so let's keep the momentum through tomorrow!

Until then,

The Docathon Team

Three quick tips for the docathon

2017-03-03T00:00:00-08:00

The Docathon is only a few days away! Thanks to everybody for agreeing to take a little bit of your time this week, and helping build great documentation.

A few folks have asked about tips for being as effective as possible during the week. Below are three steps you can take to make the most of your time.

Prepare!

The best way to make sure something gets done is to make a clear, actionable plan.

For projects, you should identify parts of the documentation that could use improvement, and create issues so that people know what to work on. Here's an example of Matplotlib's Docathon project plan. Note how issues are tagged to make it clear which are easy contributions. Also, come up with a plan for how you'll get those changes merged! Make sure you have developer time to be response for new pull requests, and be welcoming to PRs for new contributors. We've put together a short guide that gives you some extra steps to take in preparing for the event.

For participants, you should think about some projects that you'd like to contribute to (even better if they're also signed up with the docathon). Check out our projects page if you want some inspiration. We've create a page for each project that has useful information to help you get started, including a list of open doc-related issues. For example, here is the matplotlib page. Some projects have even put together a specific page to handle documentation during the docathon. For more tips, here's a short list of ideas that you can follow to get started contributing to projects.

Tag your commits!

Any documentation commits should include the words "doc", "documentation", or "docathon" in the commit message. During the week, we'll be keeping track of stats on who's contributed. This will be displayed on our lovely stats page. Below are the current leaders in both projects and users. We'll update these plots a few times each day so that we can congratulate those that have made contributions. You can also click a plot to go to a summary page.

Projects

Users

That said, our biggest goal for the docathon is to push our community towards making their projects more people-friendly. If you can say that you've done this at the end of the week, then we'll be happy regardless of what kind of paper trail you leave behind.

Reach out

Since we're scattered all over the place, our goal is to provide a little community while we're all working on this together. We'll reach out periodically via email to give updates on progress that has been made, but we'd love to see discussion going on interactively. You can take these steps to connect with others during the docathon:

Sign up for our slack chatroom. There are channels for general conversation, and a few for specific sites if you're working with one of the groups.
Tune in to the tutorials via youtube on the first day. Or if you're in Berkeley, you should join us in person! Here's a list of topics that we'll cover.
Find a working group in one of these locations. Each site has their own plan for how they'll structure work during the week. For example, BIDS will be working for a few hours in the afternoon each day (that's so we have an excuse to bring in coffee ;-) ).
Be ready to discuss documentation in your projects! For many projects there will be a flurry of commits improving documentation. Make sure to chime in, discuss improvements that can be made, open issues for next steps, and generally work as a team to get things done.

We hope that these tips will be useful in getting you up and running with the docathon. Ultimately, we just want you all to have fun, and to come out of the week with a better, more beautiful set of open source docs. We're looking forward to working along with you soon!

Don't forget to register!

2017-02-27T08:00:00-08:00

As the Docathon draws near (t-minus 7 days!), don't forget to register if you'd like to come physically to one of the host locations! During the week there will be docathon groups working remotely at these locations:

BIDS, UC Berkeley, CA: register here | Agenda

eScience Institute, UW Seattle, WA : register here | Agenda

Digital Fellows (GCDI), The Graduate Center, NY : register here | Agenda

Docathon Kickoff

In addition, on the first day we'll have a kickoff event at BIDS with some tutorials to help you build great documentation (signup here). We'll be streaming this live on the internet as well, so check back soon for a link.

How to contribute to documentation as a new user

2017-02-26T00:00:00-08:00

Contributing to a project is often a daunting challenge. Each project has an idiosyncratic way of organizing folders, accepting contributions, writing examples, etc. Fortunately, documentation is a great way to get started. You can usually make noticeable improvements to a package without knowing the full details of the project’s API, and there are always improvements to be made in documentation.

However, it can be hard to figure out how to contribute to a project’s documentation. As a part of the Docathon, there are several projects in need of some documentation help. Here are some ways that you can help out.

Review tutorials, examples, and written documentation. Ideally keeping a critical eye open for opportunities to improve the materials. This is an excellent opportunity to learn a bit more about your favorite library and propose improvements, fix typos, write a new paragraph, or improve one!

Look for issues that are labeled as documentation. Many projects have a list of issues related to documentation. Check out if there are any issues labeled Documentation and new-contributor-friendly, e.g.: https://github.com/matplotlib/matplotlib/issues?q=is%3Aopen+label%3ADocumentation+label%3Anew-contributor-friendly. If you can’t find any, you can always open an issue to offer your services as a documenter!

Improve API/function documentation. API documentation should clearly explain the usage and meaning of all inputs and outputs for functions, objects, etc. This is extremely important for ensuring that the package is easy to use. However, many packages fall short of this goal. Ensuring that the documentation fits a common format (such as numpydoc for Python projects) makes this job a lot easier. If the documentation isn’t already in a common format then submit an issue suggesting converting the documentation, or make this format switch yourself for a few functions in a pull-request. If there is already a clear formatting preference in the package, then perhaps you can improve under-documented functions or make existing documentation clearer.

Contribute new examples. Look through the examples provided in a project’s documentation and see if there are any glaring omissions. Is there some function that you use that isn’t covered in the examples? If so, you could create a short script that shows off the functionality. If you see two examples showcasing the same feature, try merging them!

Improve the language of examples. Many examples / tutorials / vignettes are thrown together relatively quickly and are often written in an unclear and overly complex way. Check the comments and narrative sections of the documents and think about how they could be improved. If you see ways to improve the language, open an issue or submit a pull request with your suggested changes.

If there are contribution guidelines, adhere to them as much as possible. This will reduce the amount of time needed to get your contribution merged into the main codebase. Either way, try to style any new contributions so that they’re similar to what is already there.

We hope this helps you get started!

Encouraging user help for the Docathon (and beyond)

2017-02-24T00:00:00-08:00

Documentation is a great way to get new users and contributors involved in your project. It requires less knowledge of the intricacies of your codebase, and can be both fun and easily appreciated by others.

However, it’s not always clear to people how to contribute documentation. At the Docathon there will be many attendees who have experience in coding, but aren’t sure where to begin. This is a great opportunity to get some work done and to grow your community.

A commonly-forgotten part of project documentation is information about how users can become developers. Each project has its idiosyncrasies and preferred contribution workflow, and this isn’t always obvious to people. We recommend the following steps:

Think about your contribution workflow. Do you have one? If not, then spend some time thinking about how you’d like contributions to occur. If anything else, it is helpful to explicitly state that you welcome contributions in the form of pull requests.

Make it clear how your documentation is organized. It’s good to have documentation split up by the scope of its content. E.g., don’t intermingle high-level tutorials with examples showing off a specific piece of the API.

Make it obvious what kinds of documentation goes where. It will help new contributors, and make it easier for new users to use your project.

Create a “documentation” label, as well as a “new-contributor-friendly” label for your repository. Come up with some ways in which you’d like your documentation to improve (e.g., #32: write an example for the statistics module, or make docstrings numpydoc compatible) and tag it with these labels. Along these lines, make your tickets as descriptive, clear, and actionable as you can. “Add references to the linear_model function” is better than “Improve documentation for the linear_model function”.

Make sure that your project has at least one or two examples that can be highlighted as “good” forms of documentation. Many users will riff off of what is already there, so if you can say “you should make your example similar in style and scope to XXX”, it will help them.

Write a short “how to contribute” guide. You might link to a guide on opening pull-requests in github, then explain if you have any information you’d like to see in the pull request.

Finally, don’t be too nitpicky about the PRs that new users make, and make sure to be friendly to new contributors! Documentation (usually) won’t break anything, so don’t let good become an enemy of perfect! Is the pull request an improvement? Just press the green button.

Remember - documentation is the first point of contact that most people have with your package, so it’s worth putting in time to make it as clear, complete, and maintainable as possible!

Why host a docathon?

2016-11-10T18:40:00-08:00

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!