Drupal Core API documentation co-maintainer needed
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.
Help with any of these items would be welcome:
- 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.
- 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.
- 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.
SkillsetThe 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!