Documentation Team

For 2009, I'm setting up monthly "Docs challenges" which I invite everyone to join in on. For the month of January I want to do a bit of house-cleaning on the documentation issue queue. I've got a blog post up on my personal blog for the details: http://rocktreesky.com/docs-challenge-january-tending-queue. If you wanted to jump in but were never quite sure how/where/what, feel free to stop by on IRC or leave comments on my blog post.

This is a summary of the IRC meeting held December 18. The IRC log is available here: http://pastebin.com/f57aa5c9e

**Announcements
- The KDI sprint funding is pending so I'm starting to plan doc sprints for next year at camps around the world. If folks are aware of camps being planned, please keep me in the loop for a potential sprints.

• Re: the OG vs mailing list conversation, Moshe is open to tieing the two together but none of the current solutions are solid. I'll be getting more info on what's needed and who might help in the next few weeks.

The Doodle has spoken. Next meeting is Thursday, December 18 at noon EST (17:00 GMT, 9 a.m. PST).

We will meet for one hour in the #drupal-docs IRC channel on the FreeNode network and discuss:

Announcements
Status on Theme guide reorg
More Getting Started org discussion
Talk about redesign status
Discuss the new help system in core issues

Let's get together for a docs meeting this week to catch up on things before the holidays overtake us all. :-)

Here is the Doodle to vote for a time: http://doodle.com/34ap6e6y24t7isv6

We will meet for one hour in the #drupal-docs IRC channel on the FreeNode network. Please vote on Doodle by Wednesday, Dec. 17 (tomorrow) midnight GMT (7pm EST, 4pm PST).

Agenda:
Announcements
Status on Theme guide reorg
More Getting Started org discussion
Talk about redesign status
Discuss the new help system in core issues

We should start to create a style guideline for the help system. This would help to make the help files consistent in look and feel. I have started a wiki page here http://groups.drupal.org/node/17300

Hopefully we can discuss how each part should look here and lay it out on the wiki.

Edit: Wiki page removed look at the other pages posted below.

Drupal 7 will (hopefully) see the introduction of a new and completely overhauled help system (read: starting from scratch).
However, this mean that all documentation must be re-written.

This is not a job for one person! We need everyone to pitch in and help (no pun intended). If everyone can write two (2) pages, then we'll be very well off.

The kind people at the Help System group on groups.drupal.org have assembled a workflow for you to take part in. Here's how to write a help page for a module:

1. Log in here. If you don't already have an account, you can log in with YOUR_DRUPAL.ORG_USERNAME@drupal.org as your usename and your drupal.org password as your password
2. Navigate your browser here to start your new wiki page.
3. Choose "Drupal Documentation Task" for the "Group categories" vocabulary; and
4. Choose the name of the module for which you are writing documentation for the "Help topic module" vocabulary.
5. Fill in the title and the body to those that you wish to appear on your help page
6. Be sure to adhere to the guidelines

If everyone can do two (2) of these, we'll have all the help pages in core done in a matter of days. And guess who it starts with? You!

If you would like to edit an existing page, simply go to the Help System group, find the page along the left, click on it, and click the edit tab.

Our current style guide for the handbooks has not been reviewed in quite a while.

siliconmeadow and LeeHunter are the leads for this project.

We have determined that there really is no need for a separate writer's guide and style guide. One place that says "this is how we do stuff here" would probably be more useful. So we need to look at consolidating the current pages:
http://drupal.org/documentation-writers-guide
http://drupal.org/about/authoring

Would also be nice if we can work on adding some sample templates for project help files (like INSTALL.txt and README.txt)

We need to make sure that we have a clear, complete Getting Started guide for Drupal 6, along the same lines as the Drupal 5 guide. We are currently discussing how to approach this. Originally we were just going to duplicate the D5 guide. We should have an approach and start implementation by Monday, November 24.

Once again, big thanks to Hans for pulling together a summary for us. The original IRC log is here: http://pastebin.com/f13c30b7a

Announcements

• Leisa from MBD has a new post up re: docs redesign ideas: http://www.disambiguity.com/drupalorg-redesign-a-strategy-for-the-docume...
• The next iteration (#9) of the redesign just went up http://drupal.markboultondesign.com/iteration9/
• The FP post re: open editing is up

So this is an issue that has been kicking around in my head for a while. It was raised briefly earlier this year on the list and it was decided to stick with the mailing list. I raised it again today during our IRC meeting to get a general pulse. So, I'm going to lay it all out and see what the larger team thinks.

I am proposing that we deprecate the documentation mailing list and use groups.drupal.org for our discussions instead. In order to not have conversations happening in two places we need to have one definitive "discussion" venue. Due to this, the current docs group is "read-only." To make it read-only we have to limit who can actually become a member of the group. Limiting membership like this severely hampers our use of all the tools that g.d.o could offer us.

We've set the time for the next IRC meeting. The meeting will be for 1 hour in the #drupal-docs FreeNode channel on Thursday, November 20, 2008 at 1 p.m. EST (18:00 GMT, 10 a.m. PST).

Agenda:

• Announcements
• Limiting page creation? (please continue this discussion on list and use the meeting to hash out remaining bits/action items)
• Next projects on radar:
  • Getting started guide for D6 needs basic content completed
  • Reorganizing the theme guides

The last meeting we covered a lot of ground and bounced around a bunch of ideas. We didn't have much time to dive into new projects, so let's set another one up soon. the meeting will be for 1 hour in the #drupal-docs FreeNode channel.

Here is the scheduling Doodle: http://doodle.com/u2xw6996qgkfd9yt (Please respond to the Doodle with your preference by Thursday, November 13.)

HansBKK is currently lead on the workgroup to help create a single, well-organized Theming Guide, and will be the main point of contact for questions. Any interested documentation team members are invited to join in this effort. Others that would like to contribute should first request to join the docs team; see the "Pitch In!" section below.

History

The original post in the documentation team's issue queue discussing this project was Reorganize Theme handbooks and the currently active one is Theming doc workgroup forming.

See the announcement for this project posted to drupal.org's front page.

Current project stage

Addi has merged the main D5 and D6 theming guides into one. There are still four other major locations for theming information in the drupal.org handbooks that are candidates for merging once we have a decent structure:

• Beyond the Basics: Theme HowTos
• BtB: Theming snippets
• BtB: Contributed themes
• BtB: Comparisons of contrib themes

plus of course many valuable contributions scattered around in other parts of the Handbooks.

HUGE thanks to HansBKK for doing the summary this time round. Here is the full log: http://pastebin.com/f31e56f30 This is the summary for today's IRC meeting, with a few edits by me:

Meeting agenda: http://groups.drupal.org/node/16343

Let's get together and whip up some Doc Love. We'll meet for 3 hours at the DC Public Library to work on Drupal and then, if folks are interested, we can go out for food and drinks after. We have a medium meeting room (A-9) reserved from 2 p.m. to 5 p.m. on Sat. November 8. (For directions to the room, see below in the Where? section.)

Our next IRC meeting will be on Friday, November 7 at Noon EST (17:00 GMT, 9 a.m. PST). We will meet in the #drupal-docs channel on the FreeNode network for one hour.

Agenda:
- Announcements
- Discuss the open editing experience. Is it working, should we continue? Thoughts, improvements? (Update: there is a thread, Open editing/limiting creation? I started on the list related to this)
- Catch up on the D.o Redesign and how it is effecting docs (Iteration 7 is up and we have a good thread on docs going)
- Discuss next projects (Getting Started guide, reorg the theme guides)

Feel free to add to the agenda and discuss open editing prior to the meeting on the docs mail list.

Well, we have had open editing for a week now and so far so good as I
have been watching. We should meet to talk about how our trial is
going and whether we want to continue to keep it open or close back
up. We can also talk about the state of the redesign. If you have
other agenda items, feel free to add.

Here is the doodle to schedule the meeting: http://www.doodle.com/667xykvs65hhyh5z

Please add your preference to the Doodle by Thursday, October 30. We will meet for one hour in the #drupal-docs IRC channel, as usual.

The redesign has been doing lots of great stuff, rethinking how we approach Drupal.org. We should take this opportunity to really think about how we present documentation on the site. There has been a lot of talk and there are lots of little nits of annoyance in addition to the larger complaint of organization with regard to the handbooks. I wanted to try to gather up at least some of the larger things for us to consider and continue the discussion so that we can focus on specific changes while we have the services of MBD available to us.

Here is a brief summary of the IRC meeting held Friday, October 10. The IRC log can be read here: http://pastebin.com/f575075de. I had to leave the meeting early due to an unplanned meeting that came up, for which I apologize, and thanks to everyone that kept the meeting running. :-)

Announcements:
- Our group page has tabs for things like projects and issues now

We have decided to open up editing rights for all users for a one month trial period. (See the mail list discussion summary.) We opened up permissions on October 15 and have decided to let them remain open. We will announce the continuation on our November 15 deadline.