Core API documentation issue squad needed!

Events happening in the community are now at Drupal community events on www.drupal.org.
jhodgdon's picture

For the past several years, I have been the person who has managed the documentation component of the Drupal core issue queue.

Several people besides me have recently started contributing to Drupal's API documentation by patching issues, and I'm very happy about that! What I'd like to do now is also get a few people to take on the issue queue management tasks as well.

NOTE: Edited Nov. 11 - added Skills Needed to both tasks.

Here are the tasks:

  1. A few times a week, check the documentation component of the Drupal core issue queue for newly-filed issues. These mostly come from the "file an issue" links at the bottom of the api.drupal.org pages. So, they need to be checked out:
    • Some of them are support requests. For these, politely inform the person that we don't do support in the Drupal Core issue queue, and direct them to other support options (I have a template that you can copy and paste). Then set the issue category to "support request" (if it wasn't already), and set the status to "fixed".
    • Some of them belong elsewhere. The most common are issues that belong in the Examples for Developers project (this project is included in api.drupal.org), or the Documentation project (there are a few files in the Documentation project git repository that are on api.drupal.org, and we use issue component "API documentation files" for issues related to those files in that project's issue queue). If an issue belongs in a different project, move it there (with a comment).
    • Some are not valid or need more information. If you investigate and don't agree with the report, you can either mark it "posponed (maintainer needs more information)" and ask for clarification, or you can mark it "works as designed" if the report is just wrong and the documentation is correct. Other status changes are possible too -- use your own judgment. In any case, always try to be polite to the person who filed the issue, and explain why you have changed the status.
    • Some are valid reports. For these, if it's a small change needed or if the report is very clear on what to change, add the Novice tag. And in any case, if you have investigated a report and find it to be a valid error in the documentation, add a comment thanking the person for reporting the problem and confirming that you agree it's a problem. You also need to move any Drupal 7.x issues into Drupal 8.x (assuming the same issue exists in 8.x), and mark them with tag "needs backport to D7", because we fix issues first in the in-development version of Drupal, and then backport to the previous versions.

    You may also want to click the Follow button to follow the issues you investigate or look at.
    Skills needed: You need to be proficient at reading PHP code, because you need to be able to definitively say that function abc's documentation does or does not correctly represent what function abc actually does. You do not need to be proficient at writing PHP code.

  2. A few times a week, check the issue queue for issues newly marked "needs review", and review the patches:
    • Make sure that the patch fixes the identified problem.
    • Make sure that the resulting documentation is formatted according to our documentation standards.
    • Normally, I ask that if someone is fixing a docs issue in one function, that they also edit the rest of that function's doc header to bring it up to documentation standards and clear English. However, they shouldn't also do cleanup on documentation for other functions on that issue, just the one(s) mentioned in the issue report.... But if the same wrong content is in related functions, it's probably OK to expand the issue to fix the documentation for the related functions at the same time.

    After reviewing, add a polite comment and mark the issue status as "needs work" or "reviewed and tested by the community" as appropriate.
    Skills needed: In addition to the skills for the first task, you also need to be able to read/understand standard patch format, and you need to know how to apply patches.

Any takers? If you're interested, leave a comment here or find me in IRC (#drupal-docs or #drupal-contribute), and I can help you get going, answer questions, etc. Thanks!

Comments

I don't have time to do this

gdd's picture

I don't have time to do this much, but I'll gladly help mentor newbs and get them up to speed. Doing API docs is an AWESOME way to start getting involved in core dev!

Mentoring new people...

jhodgdon's picture

Mentoring new contributors is indeed very useful! I would encourage anyone interested in mentoring new Drupal Core (code or API docs) contributors to get involved in the Novice office hours effort. See:
http://groups.drupal.org/node/164629
http://drupal.org/node/1242856
http://drupal.org/node/1319162

I decided not to include mentoring in the Core API Docs Issue Squad idea, because I think that the novice mentoring team is covering that part of it very well... I know that they are looking for some new mentors too.

So... this discussion is about forming a team of already-competent Drupal API Documentation writers to manage the API docs issue queue.

How much do you need to know?

mollyavalon's picture

I have been meaning to get involved in documentation for some time. But I'm not sure I have the skills for this particular project. I can read but not produce PHP, and am mostly just a site builder. I do have lots of background in documentation, instructional development, editing, and proofreading. Is this the project for me or should I look for more lightweight content?

Your question is quite apt!

jdonson's picture

Hi Molly,

I am as yet unclear about the prerequisites
for these core doc makers
and also unclear about the intended audience(s).

I would like to see some distinctions between Drupal Core
support and training docs.

I would also like to see materials differentiated according to target tech role
(Biz Manager, Themer, Developer) and towards enterprise team lamp development.

I guess this regards Drupal 7.x and 8.x platforms.

There are many moving targets there.
It looks like the Drupal core docs have become one
complex and moving target to try to tame a bit by the docs folks.

Drupal installations can include dozens of modules
which support ladders of dependencies many many rungs high.

That can be overwhelming for even a seasoned developer.

You might start with a basic sense of what
LAMP is and how PHP code works.

Note that ALL Drupal modules (core, contributed, custom)
fundamentally rely upon FIVE core modules that are ALWAYS enabled:

  1. user 392kb
  2. block 168kb
  3. node 444kb
  4. filter 220kb
  5. system 844kb

This is TRULY not much code!

The amount total php code for all 5 modules for Drupal 7 = just over 2MB

Recognizing the functions of those 5 modules is the obvious slow climb.

There is a lot of existing php code and docs.

They are both moving targets.

There are existing D7 api docs: api.drupal.org

I am not sure how docs efforts discussed here
will change or extend this existing materials.

Hope this helps!

regards~

Jeremy Donson
Database and Systems Engineer
New York City

Example api page is NOT for noobz!

jdonson's picture

http://api.drupal.org/api/drupal/modules--user--user.module/7

Is the goal to make core understandable to noobz?

Is php knowledge required?

Thank you!

Jeremy Donson
Database and Systems Engineer
New York City

Prerequisites

jhodgdon's picture

I'll add this to the page above...

In order to review API documentation patches and issues effectively, you need to be proficient at reading PHP code, because you need to be able to definitively say that function abc's documentation does or does not correctly represent what function abc actually does. You do not need to be proficient at writing PHP code.

To review patches, you also need to be able to read/understand standard patch format, and you need to know how to apply patches.

You answered my question

mollyavalon's picture

You answered my question exactly. Thank you very much. I'll see where else I can contribute to documentation.

Contributing suggestions...

jhodgdon's picture

We do have a guide to contributing to documentation... it needs some rewriting for the new status of the docs team, but most of it is still relevant:
http://drupal.org/contribute/documentation

Audience/purpose of this documentation

jhodgdon's picture

This issue queue squad is focused on the documentation that is displayed on the api.drupal.org site only.

The purpose of the api.drupal.org site: It is reference information on the Core Drupal PHP code. It is not information for users of Drupal -- it is for module/theme programmers. Nor is it intended to be a tutorial on how to write modules/themes -- it is simply a reference to what the functions, classes, constants, etc. in Drupal core do, their function arguments, etc.

Sorry Jeremy for any confusion!

thx!

jdonson's picture

Not confusing to me, but for many new to Drupal it is!

Are there any ways to graphically depict module dependency trees?

Thank you very much folks!

Jeremy Donson
Database and Systems Engineer
New York City

Please move to a different discussion...

jhodgdon's picture

This post is only about forming a team to manage an issue queue. Please post your question in the support forums, where it would be more appropriate. Thanks!

I am interested

gargsuchi's picture

Please suggest how I can get involved.

Just do it!

jhodgdon's picture

One thing you can do is start by just following the steps outlined above -- checking the issue queue, and responding (politely) to issues and patches.

But I don't know if you have done much work on API documentation -- I don't recall off-hand seeing you supplying patches? If you have and I forgot, sorry! If you haven't created any API documentation patches, you might actually want to start by writing patches for a couple of issues. In the process of getting them to pass review, you might learn about standards, process, etc. You can find plenty of issues at the above links (filter for "active" issues to find ones no one is working on yet).

The standards are at http://drupal.org/node/1354 if you haven't seen them before.

Thanks!

interested!

Sree's picture

I am interested to take this up ....

Sree

Great!

jhodgdon's picture

See comment above about how to get started. :)

Documentation

Group categories

Event type

Post type

Group notifications

This group offers an RSS feed. Or subscribe to these personalized, sitewide feeds:

Hot content this week