Docs Challenge January: tending the queue

With the start of the new year, I've decided I'm going to run a monthly "Docs Challenge." I've got another post coming down the pike that lays out my long-term goals and the big pieces of the Drupal docs puzzle for this year. One of those goals is to find ways to make contributing to documentation clearer and easier. By setting up monthly challenges, I want to outline and give guidance on docs tasks throughout the year. It is one thing to tell people they can help and give them the tools, and quite another to actually explain what that means and guide them through the process. These challenges will hopefully not only get needed documentation tasks done, but show everyone exactly what it all means and that they really, really can help out. So, without further ado, my Docs Challenge for January is to clean up the docs issue queue on Drupal.org. We currently have about 200 issues covering 4 pages. I'd like to get that down to 150 (3 pages) by the end of the month. To that end, I'm going to set aside at least one hour each weekend day in January, from 1-2 p.m. EST (18:00-19:00 GMT) to work on the queue. I'll spend that hour on IRC in #drupal-docs on Freenode to answer questions and teach anyone who wants to learn as well. Fifty issues is a lot to get through and I'm going to need at least a little bit of help.

What are we doing now?

The Drupal documentation issue queue is the main work area for docs, much like every other project on Drupal.org. As the documentation lead, I see it as my main queue to look after, in addition to my regular module queues. It isn't just my queue though; our documentation is everyone's project. We are all maintainers for the docs queue and it can be a bit disheartening to go to look through issues and see you have several hundred to get through. In addition to the sheer volume of work that is so discouraging, it also makes finding things to work on and keeping things organized that much harder. A large, messy queue discourages contributors and really overwhelms new folks who are just starting to help out.

There are a few ways you can help. You can jump in and start fixing issues right away. Many issues are about places in the handbooks that aren't clear, need to be updated or are just plain missing. Everyone with a Drupal.org account can edit most handbook pages as well as create new pages - no special rights needed. We also have a number of issues that need more discussion before they can be resolved, so taking the time to read the issue and provide thoughtful feedback is needed too. It doesn't require technical skills, just some time to read, think and express yourself in a constructive way. Besides actually jumping into the issues themselves, an often overlooked but sorely needed area of help is with "queue tending."

Tending to the queues are an important job and the docs queue is in need of this love as much as any other large queue. Tending queues, no matter the project, is something everyone can help with. The two biggest pieces that help keep things organized are simply checking to see if an issue is still valid at all or a duplicate of another issue, and finding important issues that have gotten buried under the load and bringing them back to front of the line. Angie (webchick) talks about this for core in her "We need farmers and pirates" post, but the same basic concepts apply to all issue queues.

Hm, how does this work?

It sounds great in writing, but how does it really work? A lot of people are not comfortable going to the issue queue; it is perceived as a weird, esoteric place. Most new people (including myself when I was new) feel like they might break something, or do something wrong, or they aren't sure if they have the proper right or authority to change things. The bottom line is that the issue queues can be intimidating generally and the docs queue tends to add more confusion into the mix because we are using a code-focused ticket system for documentation. If you do find an invalid or duplicate issue, what do you do? What do all those fields mean? Who gets to say this is "fixed?" And that doesn't even get into the main part of it where, ya know, we're supposed to actually fix the issues that are reported. ;-)

Now, we have started an issue queue section of the handbook and there is a really nice description of the issue submission form, which uses the docs queue as the example. We also have a page specifically about using the docs queue. These are great references and I'd like to make them better throughout this month by getting feedback from you. Yes you. Why you? Because you are going to help me out and in the process you'll probably find lots of little rough spots where the documentation is lacking or confusing. Even if you only take 10 minutes a week to look through some old issues and give feedback, it'll help everyone out. We will not only be making Drupal docs better but we can help more people feel comfortable using the main working tool of our community. That is a whole lotta win. I'm starting on January 3rd at 1 p.m. EST, but if you can't make it then or the other weekend days, you can just hop in and leave questions as you go. If anyone else would like to set up their own "challenge hour" in the IRC channel, let me know and I'll be sure to post it. See you in the issue queue.

Comments

Hi,

I am very happy to see the documentation effort underway, both as a Drupal newb, as well as someone who cares about good documentation and support in general (Is it any wonder they made me run the Customer Support department at one startup I was at? :)

I have had one issue with doc issues referring to pages that are not generally editable. For example, this issue on hook_menu refers to this page on the v6 documentation of hook_menu. I (sort of) understand the question and could investigate its solution, but how do I edit the actual page. What is the role of the larger community with issues like this --- is it to tag them in some special way so that they can get noticed by the core doc team that has the perms to edit these pages?

Hi Sameer, and welcome. :-)

That particular page, at api.drupal.org, is actually generated edited in CVS. Anyone with a CVS account can edit the API "topics" pages and hooks. The functions themselves are being pulled directly from Drupal core and so require a core patch. API documentation is actually not considered a regular documentation team issue because of the CVS/core requirement. That issue, and others like it, should be moved to the "Drupal" project, "documentation" component, issue queue (and this is definitely a helpful thing to do in terms of tending the queues and making sure the right issue is in the right place). We have a page that explains a bit more about updating API docs.

For other pages in the regular handbook that you cannot edit, we have an explanation and partial list on the Locked pages page. Most of those pages can be edited by the documentation team. Some pages are even more restricted and can only be edited site maintainers. For issues that you encounter about those kind of pages, just leave a reply in the issue with your proposed edits and state that you don't have rights and someone with elevated rights can make the update.