Write the Docs: Jennifer Hodgdon – Motivating developers to write API documentation

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Jennifer is the API docs coordinator for Drupal. There are a few ways to get API docs written. First, no one writes the docs. This isn’t ideal. Second, you can hire tech writers to write the docs. This is only viable in a corporate project and may not even be desirable there. Finally, developers can write the docs. This is probably the only viable solution for Open Source. It’s probably desirable for most corporate projects, too.

When Drupal 7 came out about 2 years ago there was a lot of improvement in documentation. Jennifer submitted 278 patches which is awesome but not entirely sustainable. A similar trend held across the work in usability, accessibility, and performance in the project.

For Drupal 8, the method is to enlist the entire community in documentation. To do this a few things must happen. There have to be written standards for API docs. There also has to be a culture where bad documentation is treated as a bug. Finally, you need to create a culture in which patches without minimal docs are unacceptable.

Core gates in Drupal aim to solve the problem of getting to the end of a development cycle with code that has poor usability, documentation, test coverage, and more. To fix this all patches must pass through “gates” before commit. These gates are listed on the Drupal site. In practice it’s sometimes enforced and sometimes not.

The documentation gat means that all functions, classes, hooks, methods, and more have to have at least minimal API documentation. One line summary of what it does where all parameters are documented and the return value is documented. There are a few other aspects, as well, but that’s the core.

All API documentation for Drupal is embedded in the sourcecode. Having those separate will only lead to inconsistencies. You can still generate an API documentation site but the docs must live in the code.

Another neat thing they do, particularly with documentation, is use a “novice” tag for certain bugs. This is added to issues that are relatively easy for a novice user or developer to contribute to and patch. It helps bring in more contributors as well as get things fixed. They support this with Core Office Hours and a mentoring program that helps people get development environments set up.