Reorganize the theme guides

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.

Note that some sets of theming-related pages will not be moved:

• all the automatically generated pages within the automated API documentation system, e.g. core template.php
• the stream of discussions flowing through the forums
• those pages pertaining to specific contrib modules, e.g. Theming Views
• and BtB: Theming videos and slides

In fact, module-specific pages currently in the above locations will be moved out to the relevant module's doc pages.

Team tools

To help them classify and re-organize the relevant pages, the team will be using Diigo, a "social bookmarking" tool, where they have created a group called drupal-docs. Diigo's capabilities include:

• a group can share bookmarks, and create a standard set of keywords for tagging pages
• comments threads automatically show up while members are browsing, right on the handbook page being discussed
• "sticky notes" can contain discussion about a particular section of the page, as can specific highlighted text
• no copy/pasting links and text back and forth
• less chatter cluttering up the main doc team's discussion channels
• works via browser extension (or bookmarklet) + diigo.com web interface

Pitch in!

Successfully completing this project will be a lot of work, so all qualified Drupallers are invited to join in and help; any level of participation is welcome. As this is a sub-group of the documentation group, you must first be a member of the docs team; here's how to join. You should also have a "reasonable" amount of theming experience, although relative newcomers can contribute valuable feedback from a newbie's POV, and will certainly learn a lot by participating in the project.

Once accepted to the main team, first sign up with Diigo, then come to drupal-docs there and request to join the group.

Play around and become familiar with the toolset, by creating some private bookmarks; try commenting via sticky notes and highlighting text, as these are immediately visible on the page for any team members coming by. Then go to the head of the theming guide and try posting some sticky notes to pages there and sharing them to the group. Also check out the group's Diigo forum.

It is important for the rest of the docs team to not be excluded from important discussions, so the workgroup will post its recommendations for feedback, via issues posted to the main documentation queue, before making major structural changes, and give a status report every couple of weeks.

We are also putting some guidelines in place for using Diigo specifically. These guidelines will be regularly revised as needed, so theming workgroup members using this tool should return here to review them once in a while.

Note we are also investigating other tools, in particular real-time collaborative editors.

Diigo guidelines

• drupal.org is primary
• Diigo's discussion facilities should primarily be used for "meta" issues like page classification and navigation hierarchy
• substantive discussions about page content or other issues should take place in the main docs-team channels on d.o., where you're also likely to get better answers
• target pages - bookmarks and page annotations shared to the group should be
• to/on drupal.org pages only, and
• for now, limited to theming-related pages only
• feel free to link to any other relevant pages within your comments, or create your own group for talking about other topics on Diigo
• what kind of "Diigo spoor" to use
• don't use page-level comments, they are only visible with the sidebar open
• only use page-level bookmarks for tagging (see standard tags below)
• post sticky notes to the top of the page for page-level comments
• start a new sticky note if you're starting a different topic = "topic thread" for the page
• or if one gets too long (summarize first)
• use highlights and comment within them when discussing specific text on the page
• don't highlight whole blocks, just enough to show what you're referring to, e.g. subtitles
• if you're motivated, clean up your no-longer-relevant comments, unless you think others will need to reference them

Diigo tags defined for drupal-docs group

version applicability tags

Use these to tag theming-related pages, ideally via a sticky with any comments. If the node as a whole is mixed (D5!6) then maybe flag which bits are which with text highlighting. D6 topics that apply to D5+Zen should be explicitly labelled as such. Substitute D4 or D7 if needed.

Feedback on this topic can be posted here

Current members on Diigo

• Heather - (nearlythere)
• Addi (add1sun)
• Richard (siliconmeadow)
• Hans (hansbkk)
• Lee (leehunter)
• Wolf (wolfflow)
• Shai (shaigluskin)
• dvessel
• Alexander (alexanderpas)
• Emma Jane (emmajane)
• Trevor (trevortwining)

Reference: past discussion on Diigo

The Big Picture

As part of the current overall drupal.org redesign project, there are more general discussions going on about a full re-structuring of Drupal's documentation.

The documentation team's reorganizing the theming content should help build our capacity to contribute to the larger project as well.