Upgrade Your Drupal Skills

We trained 1,000+ Drupal Developers over the last decade.

See Advanced Courses NAH, I know Enough

Drupal Core API documentation co-maintainer needed

Parent Feed: 

For several years now, I've been serving as the API documentation maintainer for the Drupal core project. It's a job that I enjoy doing, since it combines working with the Drupal community (especially new contributors) and improving API documentation (somewhat of a passion). But it's a pretty big job for just one person, and lately, I've been taking more "personal time" (traveling, not working a full 8 hour day, etc.), and I've had less time to devote to it. So, I'd really like to find another person or two, having at least some level of experience with Drupal core development, to share the job.

Clarification: I'm talking here about the API (programmer) documentation that you can see at api.drupal.org, which is generated from specially-formatted comments in the Drupal Core PHP source code, and modified by updating Drupal Core PHP source code.

Job description

Help with any of these items would be welcome:

  1. Triage new issues that are filed in the Drupal core project in component "documentation":
    • Sometimes they belong in a different component or a different project, and can be moved there.
    • Sometimes they are really support requests (someone needs help either using Drupal or programming with Drupal); in those cases, you can politely steer them towards the https://www.drupal.org/support page where they can find more appropriate resources (we don't handle support requests, as a general rule, in the Drupal core issue queue).
    • Sometimes they need an update to the title and/or issue summary for clarity, so you can do that.
    • Sometimes they don't make any sense, and you just need to ask the person who filed it for clarification, and set the status to "Postponed - maintainer needs more info".
    • Sometimes they are straightforward, easy-to-fix issues; in that case, add the "Novice" tag and someone will soon make a patch.
    I usually try to check for new issues in the documentation component every few days and triage them appropriately. And always say thanks for filing issues (if they're not filed, they won't be fixed!)... except for the Support requests, where a polite tone of "Sorry, but we don't do support here so you'll need to look elsewhere" is more appropriate than a "thanks" vibe.
  2. Review patches (in the same documentation issue queue) for:
    • Accuracy - does the patched documentation match what the code is actually doing?
    • Clarity - is it well-written, easy-to-understand documentation?
    • Completeness - are there more points that need to be made? Does the patch cover all of what was stated as problems in the issue title and summary?
    • Standards - does the documentation conform to our comment and documentation block standards on https://www.drupal.org/node/1354 ? Will included code examples work, and do they comply with the Drupal project coding standards and best practices?
    • Copy - punctuation, grammar, good English, spelling, etc.
    If the patch does comply with these points, mark it Reviewed and Tested by the Community. If not, mark it Needs Work, and provide detailed, polite feedback on what needs to be changed. Especially for new contributor patches, if the wording is awkward or unclear, a specific suggestion of new wording is very helpful. And be sure to say thank you to the person or people who supplied patches, and keep the tone polite and respectful.
  3. Committing documentation patches: This is part of my "Core Maintainer for Documentation" job description, but at least for now, that wouldn't be part of a new person's job description.

Skillset

The ideal person or people for this job will have the following skills and attributes:
  • Knowledge of how the Drupal core issue queue and patch workflow works (someone who has not worked on any Drupal core issues would probably not be best for this job, yet).
  • Knowledge of the comment/documentation standards (this can be learned on the job, but ideally the person will have made some API documentation patches in the past).
  • Attention to detail.
  • Caring about improving Drupal documentation.
  • English grammar, punctuation, etc.
  • Patience - many of the people contributing documentation patches are novice contributors, and you'll see the same mistakes made over and over, sometimes repeatedly by the same person. It can get frustrating, and it can be difficult to maintain a polite, respectful, thankful tone.
  • PHP coding - you'll need to be able to at least read PHP code and figure out what it is doing, in order to assess whether a patch contains accurate documentation of what the code does. This may also involve some sleuthing, such as seeing how a function is being called, how the return value is being used, or what the classes implementing an interface method are doing.
  • General knowledge of Drupal 7 and 8 (mostly 8) APIs would help, but you can definitely improve those skills as you go.

Any takers? You can jump right in on issue Triage and Reviews (as described above), without asking for permission. Or if you'd like to discuss it with me, find me in the #drupal-contribute IRC channel or contact me via my Drupal.org contact form (I'm assuming anyone who's right for the job would know how to do that -- I'm jhodgdon on both). Fame and gratitude can be yours, in just a few hours a week!

Author: 
Original Post: 

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web