Docs Challenge March: Style guide review

I know I'm a bit late on the monthly challenge this time around, but between the Usability sprint and Drupalcon I've been a bit too hectic to get a post written up. So this will be a short month, but hopefully we can rock it anyway. This month the focus will be on spiffing up our handbook by reviewing what we have and applying the style guide to it. Much like how the coding standards make working with Drupal code a lot nicer (especially for newbies), having consistency and clarity in our handbooks will make it easier for people to understand the firehose of information on any given page. I found that the best way for me to learn Drupal coding standards was to review existing code and help fix it. This month's task should not only help us clean up the docs a bit, but also get more people familiar with the fact that we even have guidelines as well as tucking some things into the back of their minds for next time they write or edit.

One of the deliverables from Mark Boulton Design for the Drupal.org redesign was an editorial guide. One of the great accomplishments at the Drupalcon doc sprint was getting that new editorial guide incorporated into our existing handbook style guide. Now that it is in place, we have a lot of pages to be reviewed and edited to bring them into line with it. The process here is pretty straight-forward: read through the style guide and then pick a section of the handbook you'd like to work in. Read through a page, see how well it lines up with the guide (and also check for typos , dead links, etc.) and edit where needed. Don't worry about "duplicating" effort either. There is nothing wrong with having 10 people review the same page. Each person may see something different and so many eyes will make for a shinier page. This is especially true on top-level and popular pages (yeah, these need updated but srsly the most popular pretty much stay popular), so have at and don't worry if someone else might have already looked at it. Another helpful task while going through these pages is to double-check the vocabularies assigned to the page. We have a few ways of tagging handbook pages now and the more info we have, the better we will be able to find and organize them. You can read more about the vocabularies at the bottom of the handbook structure page in the style guide.

The style guide is in the Getting Involved handbook, under the Contribute to documentation section, but my favorite way to get to it is to use a handy sidebar link. If you enable the "Documentation team links" block for your Drupal.org account, you will get a list of commonly used links in your sidebar, including a nice link directly to the style guide page. You can enable this block by following these easy steps:

  1. Log in to Drupal.org (if you don't have an account yet, make one)
  2. Go to My account
  3. Click the Edit tab
  4. Scroll down to the Block configuration section and check off the Documentation team links box
  5. Click the Save button

After you save the change, take a gander at your right sidebar and you will see the new shiny block, eager to help you. If you need to ask questions, bounce ideas or generally just want company while working on this stuff, feel free to swing by the #drupal-docs IRC channel on Freenode. I'm going to carve out an hour a week myself to hang out in there. I'll be working on the style guide every Monday for the rest of March from 7 - 8 p.m. EDT (4 p.m. PDT, 23:00 GMT). Let's make it spiffy!

Comments

3 cheers for Mark Boulton, and the 3/7 doc sprint team who buckled down on making that style guide rock! :)

So I take it this means we're safe to host a little doc sprint at our office this week or next, even before your Toronto meeting?

Don't wait up for me. There are plenty of opportunities for more sprints down the pike and we definitely want to keep momentum up. :-) Lemme know when you plan it and if I'm free I'll come down to help out.

And a big Thank You to you Margaux, for taking on grand poobah cat herder role, both at the Drupalcon sprint and here in DC! (I think we should have a new role called "grand catbah.")