April-May Programmer-Doc Sprint

We encourage users to post events happening in the community to the community events group on https://www.drupal.org.
jhodgdon's picture
Start: 
2011-04-19 (All day) - 2011-04-23 (All day) America/Los_Angeles
Organizers: 
Event type: 
Sprint

I'm hereby launching an April/May sprint for programmer/themer documentation folks! The April/May goal is to complete the Drupal 6 -> 7 module and theme update guides:
http://drupal.org/update/modules/6/7
http://drupal.org/update/themes/6/7

Background: In the Documentation team, we have a number of topical sub-groups, where people can sign up to focus on their areas of expertise and/or interest. Recently, ArianeK launched a new tradition in the Documentation Team: "sprints" where the team can focus on particular issues for a specific time period. The April 2011 sprint includes tasks for several topic areas, but doesn't have much for the part of the documentation team that I focus on: the folks who know their way around PHP and module or theme development, but who choose to donate their valuable time to contributing to documentation. So... it's a little late, but this sprint is for module/theme developers who write documentation.

Sign up or comment below if you are interested! I'll also be participating with Ariane in the "Doc office hours", every Tuesday from 1pm to 2pm, West Coast US/Pacific time (Los Angeles time) -- the next doc office hours are TODAY -- - and here's a link to find the time in your time zone.

Note: The event is shown to last only a few days, because that's how events are done on groups.drupal.org, but this event actually lasts from April 19 to May 31 (though if we finish early, that would be cool too).

Details of the sprint tasks

Background on the Module/Theme Update Guides

For Drupal 6 to 7, the Module and Theme update guides (see links above) are basically lists of "change items" (I just made that term up). Each "change item" explains something that changed in module development or theming between Drupal 6 and Drupal 7, the idea being that if you are updating a module or theme from Drupal 6 to Drupal 7, and you run into a problem, you can go to those pages and find out how you should change your module/theme so it will work. Each change item is also listed in the table of contents at the top of the page, with a link to the change item in the text below.

These pages are only somewhat useful (especially the module page is HUGE) -- and hopefully this way of documenting changes will be different/better in Drupal 7 to 8, but that's another topic. For now, this is what we are working with.

The format of what should go into a change item is slightly different between modules and themes. Good examples:
Modules - http://drupal.org/update/modules/6/7#drupal_set_title
Themes - http://drupal.org/update/themes/6/7#search-result-headings
Note that each of these examples has a verbose title, links to the relevant issues, a written explanation of the change, and code examples for Drupal 6 and Drupal 7.

So... Drupal 7 has now been out for a while, but not all of the changes in Drupal 7 have yet made it into the Theme and Module update guides. In fact, there is a whole page of issues tagged "Needs Update Documentation", which need to be added to either the Module or Theme update guide.

Documentation Writing Task

The main task of this sprint is to write missing documentation sections for the module/theme update guides.

  1. Find an issue tagged with Needs Update Documentation that interests you.
  2. Figure out what change between Drupal 6 and Drupal 7 needs to be documented:
    • This might involve reading the issue comments and/or the patch.
    • You might start at the bottom of the comment list if there are a lot of comments.
    • You might use your browser's control-F search to find the comment where the "Needs Update Documentation" tag was added, because that will likely explain what needs to be documented.
    • If you try to figure out what needs to be documented on an issue and you can't easily figure it out, change the status to "postponed (maintainer needs more information)" with a comment that asks for clarification of what needs to be documented.
  3. Write the needed documentation:
    • If you have edit permission on the module/theme update guide page (http://drupal.org/update/modules/6/7 or http://drupal.org/update/themes/6/7), add a section to the page with the needed documentation. Be sure to also add it to the table of contents at the top of the page. When you are finished, add a comment to the issue, with a link to your new section.
    • If you don't have permission to edit the module/theme update guide page, post your suggested section as a comment in the issue.
  4. Change the issue status to "needs review", so that someone can review your suggested changes.

Other Tasks

  • Reviewing issues from above that have been marked with status "Needs Review". If you agree with the changes, and they've been added to the update guide page, you can mark the issue "Fixed". If you agree with the changes and they still need to be added to the update guide page, you can mark it "Reviewed and Tested by the Community", and hopefully someone with permission (ping me in IRC!) will add it to the page. If you think it needs work, explain why in an issue comment, and change the status to "Needs work".
  • Sleuthing issues from above that have been marked with status "needs more information". Do the detective work to figure out what needs to be documented. This might involve reading all 100+ comments on an issue, or asking the author of the patch(es) on IRC what went on, etc.

Questions?

If you have questions, post them here or find me on IRC -- and let's get this done!

Comments

I'd like to help

schiavone's picture

I'll check the queue. Might need to get pointed in the right direction.

IRC handle is schiavo
email is daniel@snakehill.net

Go theming!

sylvain_a's picture

Great to see the theming topic in the spotlight.
Perhaps more people could sign in at the Docs topic sub-groups page so we can be in touch more easily? http://groups.drupal.org/node/125669

thanks for organising!

jshamley's picture

I am interested in helping, I will start with a needs update topic and go from there.

thank you for organising the documentation process!

If you need orientation...

jhodgdon's picture

Great to see people who are interested in helping! I'll just reiterate that if you need help getting started, beyond what's above, I'm often in the #drupal-docs IRC channel, and especially likely to be there during our Tuesday Docs Office Hours.

Documentation

Group categories

Event type

Post type

Group notifications

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