reorganize Theme handbooks

I've floated it to the top of the list. I'm leaving this open because you are right that this section should not live in a version-specific book but we currently don't have a "generic" theme book. We need to come up with a better solution but I don't have any obvious ideas right now.

wait, wasn't this traditionally in the developers handbook?

Why would it be in the Dev handbook when *everything* else specific to theming is in the Theming handbook(s)? This is simply a problem created by splitting the previously single theme handbook into two versioned ones.

Changed the component to reflect the new component categorization. See http://drupal.org/node/301443

Marked #317357: Shall we redesign the "Theming Guides" handbook? a duplicate. Renaming this slightly to be clear of the wider nature of it.

In reference to http://drupal.org/node/317357#comment-1055756 (with some changes)

Here is my initial suggestion:
Handbook: Theming Guide (probably change the title? landing page with some intro and merged info from http://drupal.org/node/221881)

• Anatomy of a Drupal theme
• Theming Drupal 6
• Theming Drupal 5 and earlier.
• Theme coding conventions
• Theme screenshot guidelines
• Troubleshoot your theme
• Updating your theme
• Contributing your theme to Drupal.org

FYI: Summary of:

_{excerpt from http://drupal.org/node/317357#comment-1055799}

_{Edit: @JohnNoc and I did the same think.}

The D6 Theming handbook is excellent, but I think it was a mistake to develop it in isolation when so much of it applies to D5 PHPtemplate theming as well, and much of what got left in the "old" book applies to D6 as well, but the points of departure are not clear - makes the whole docset much less usable for someone learning theming from the ground up.

FWIW I have the same objection to all areas of the handbook that have split by version - a lot of relevant content gets swept under the rug and effectively abandoned when it could/should either be incorporated into the current docset or clearly marked as "only relevant to version X and prior".

And who's to say what version is "current" at any given point anyway? The choice of version is always a moving target based on myriad factors, not least of which is the skill/experience level of the developer/designer.

I know it's a lot of work, but IMO there should be a single canonical theming handbook, with the main backbone being content relevant to all PHPtemplate theming and then sub-pages for version-specific additions/exception information.

Those with more time and less knowledge could perhaps help out by posting issues with questions about the relationship between different handbook pages, and then once authoritative answers arrive, do the "grunt work" of moving information around to consolidate it all, posting notices for a given section to be reviewed once done.

I'd be willing to help with this once I've basically finished the image-handling modules comparison. . .

add1sun wrote at http://drupal.org/node/317357#comment-1055790

Let's put it all in the pot, stir it up and see what we come up with. I also want to touch base with Mark Boulton Design to see if/how much they plan to look at IA within the documentation.

MBD's prototype iteration of the documentation section
http://drupal.markboultondesign.com/iteration4/documentation.html

The present prototype is linking to "Theming Guides" which strengthens my initial comment on the issue at http://drupal.org/node/317357#comment-1055756

At present, theme guides for Drupal 6 and 5 and earlier versions are separate handbooks. It is not consistent with the organization of other handbooks. It seems that Drupal 6 theme guide is the Theming Handbook. IMO, the theming handbook should have general info on Drupal theming with sub-pages for specific versions. If the top-level theming handbook is version specific, then we have to redesign/rewrite the handbook whenever a new major version gets released. So I propose a top-level handbook page (landing page) for consistency, better organization and forward thinking. Also, creating a top-level handbook page for theming opens up possibilities of creating sub landing pages on other theme related info like best practices, tips and tricks, etc.

IMO, we have the info, suggestions and people who are willing to contribute to do this task already. The drupal.org redesign discussion for documentation (GDO: Rethinking documentation) doesn't conflict with this as well. I also think that the suggestion at #8 addresses the comments of David_Rothstein (#4) and HansBKK (#10), so we can probably go from there. So, I am wondering what else do we need to consider. Are there things still that are stopping us from doing this task already?

I agree the current split is confusing and bringing it all back together makes sense. One more thing that definitely needs to move out from under D5 is the section on other theme engines - that has nothing to do with version. I think that the D6 intro page (http://drupal.org/node/221881) could be used as the overall intro page. I'd like to run the outline by folks on the doc mailing list (i.e. email the list asking folks to look at this issue) and in particular we should solicit feedback from dvessel, who wrote the D6 guide. So, if someone could take those two tasks on, that would be a good next step. I can also add this to the agenda for the next IRC meeting on Nov. 7.

I would also really love a review of the D5 and D6 books to mark where there is overlap and where the real differences lie and rework it so that only things that are really different between the versions is in a "numbered book."

Excellent!

However,

rework it so that only things that are really different between the versions is in a "numbered book"

I would strongly like to advocate that the books have a "backbone" of "applies to current mainstream" (IMO currently D5+D6) and then under each topic sub-pages "applies to D4+D5", "applies to D6+D7", "applies to D7 only" etc. The version applicability will need to some extent drive the granularity, and the "main page" for that topic would occasionally need "See also" references.

This will make things easier to maintain in the future, and also much more usable for those learning these topics for the first time with a given version but needing to keep awareness of the next version up during transition times such as now (D5 to D6 for newbies, soon D6 to D7 for the bleeding-edge people)

Please don't allow separate whole version-specific sections for the inverse reasons - much harder to then merge information back together later, and creates the current "find a needle in a haystack" situation for people trying to get the full picture on a given topic.

If you (Addy) feel differently, then at least put this specific suggestion up for discussion/vote?

Thanks

PS Ultimately I think we really need to find a platform for Drupal docs that is better suited rather than Book, perhaps even considering (heresy I know) only hosting it on Drupal as final output, not the creation/maintenance platform. I'm not qualified to suggest, but I suspect it would be based on XML wizardry. . .

Hm, I don't think I am entirely following how what you want is different from what I said. Could you sketch out a specific example so I can get it better?

If I can jump in here, it does seem that you are discussing different paths. If I understand correctly, it's the idea of a single theming guide encompassing all versions as opposed to one central theming guide with some separate version specific guides. Please correct me if I'm wrong.

I would definitely prefer the former option if it's feasible. It's a little hard to say for sure whether it would work without sorting through all the current theming documentation.

The only way I know how to do a big restructuring/consolidation job like this is to actually print out every single page and see what you've got. Find all the areas of duplication and inconsistency. Try and identify gaps (not so easy to do). Figure out the major topics and physically sort the pages. See how much version-specific information is actually there and see if there's a way to incorporate it into the single guide, in some cases it might just be some a note at the bottom of the page.

I'm also wondering whether it would be feasible to do something like conditional text (a la FrameMaker) and flag version specific chunks of text with a . That way the reader *could* actually select the "Theming for Drupal 5" title but what they see is actually the same single-sourced guide but with the content for the other versions filtered out.

That's the way it's always done in traditional technical communications, but I don't know whether it would work in a more ad-hoc setting. Something to think about anyway.

By your use of the phrase "numbered book", I interpreted you don't mind having a D5-specific book.

I think books should be by topic only, with the "main spine" being oriented towards less technical (not for dummies, just early in the learning curve). Sub-pages for version-specific, or "by audience" targeted docs, or a parent for snippets on that topic another parent for recipe/howto's, etc.

But everything about e.g. overriding theme functions in ONE place, not v4.7 stuff buried over here, firewall between D5 and D6 materials when they share a lot in common.

Oh jeez, I'm sorry I totally see where I screwed up. when i said "numbered book" I didn't really mean another *book*. Whoops, sorry for being sloppy with terminology. What I meant is what Hans and Lee are talking about: one book that covers theming and if there are version specific differences on a topic, then make sub-sections under that topic to address the limited scope differences.

more here

and here

_{edit: @wolfflow Link correction}

And this is what's clearly stated in the docs guidelines.

So do we need to have a decision-making process or can we start to discuss how to start merging those topics which are currently firewalled/scattered?

@HansBKK sorry but your second HERE link is missing. Have corrected!

I think we are all on the same page re: overall goal, we just need to figure out how/where to merge and what that would look like. So, we have an overall outline up above at #8 (with the addition of theme engines). Does that look good? If so, what pieces of the existing books move where? This is the PITA part that Lee was talking about. Now, when we did a similar exercise with the Getting Involved book, we had a final target outline and then made an issue for each section so that we could "fill" the outline with the URLs for existing pages and identify gaps. That pretty much worked but it wasn't ideal so do folks have recommendations for the best way to do this *collaboratively* (i.e. are there online tools to help us do this without going insane)?

are there online tools to help us do this without going insane

I've been using http://www.diigo.com/ for discussing prototypes and example site designs with clients, also notes to myself on my own image-handling HB pages.

Post comments, highlight sections, back and forth discussions all via a Firefox sidebar, so far works really well.

Issues could just point to pages in question and those working on them can just stay on those pages rather than bouncing back and forth to the issue queue.

Major changes, final drafts for approval etc could be posted back to the queue for wider feedback. . .

@ Wolfflow Thanks, I went to fix it and suddenly it was working! :)

So for example with theming, do we start a new book called "Consolidated theming book", starts out empty?

Or take the D6 book as a starting point and start to move everything else in as sub-pages?

My thinking (stated elsewhere sorry to repeat) is that the main pages should cover what's in common between D5 and D6, sub-pages for stuff that applies only to one or the other (or D4 or D7).

Main pages' target audience is relatively low on the learning curve, sub-pages for hardcore tech or "for dummies".

Sub-pages as parents for snippets on a certain topic, or recipes/howtos.

But all of these hanging off the main page on a given topic, none of these other factors to be "firewalled" off in other locations.

Obviously cross referencing between sections where needed.

I think we need to start from scratch and rethink what we are trying to do. I definitely wouldn't want to see the Drupal 6 theming guide used as a starting point.

Most people come to documentation out of desperation because they can't figure out how to do certain specific tasks and unfortunately the D6 theming guide in its current state provides very, very little in the way of practical, step-by-step instructions and what little is there is buried inside lengthy conceptual discussions. It's not that it's bad writing; they are really interesting, lucid and knowledgeable essays which certainly helped my understanding of the world of Drupal theming. Unfortunately, it fails the test of good documentation because it doesn't tell me exactly and succinctly how to do the things that I want to do and it's not organized around sets of related tasks.

The difficulty is that the bulk of the guide's information architecture is oriented toward explaining technologies rather than solving problems. Out of all the major headings, only the "Overriding themable output" heading gives hope that it's going to provide immediately useful information (but doesn't quite deliver on the promise).

Just as an aside, I'm not speaking theoretically here, I've actually been trying to solve a very basic slightly-past-newbie theming problem for the past week. Since nobody I work with has any Drupal, PHP or even CMS knowledge, (and I'm pretty clueless when it comes to PHP) I rely heavily on the documentation. I realize that I don't necessarily represent every user, perhaps just the bottom of the user barrel, but I can at least say that the approach used in both the D5 and D6 theming guides does not meet my needs.

The theme snippets section (along with any howtos) absolutely belongs in the theming guide. From the user perspective, this is the stuff I'm looking for when I go to the theming guide. I'm not writing a master's thesis on Drupal, I just need to get something done, like change the default text in the login form.

But just dumping in the existing long, long, long list of theme snippets - there must be well over a hundred - would not help me very much (except that at least I could find them where I'd expect them to be). They would still have to be organized into groups of related tasks and edited to remove duplicated and overlapping information.

I agree with Lee as for Newbies want to play first with Drupal theming and need clear simple and step by step example on how to implement some default changes. I hate the long discussion and paraphrasing that really one can use for getting to sleep. :-) Please I do not want to offend anybody but We are here not on a literal award site!

I find that it will be a huge task to select those default actions that may build up the Theme Handbook Section add missing example for each version and for theming samples. I really do not have any good suggestion on how to manage that. I can also say that meanwhile I see and read many of this kind of discussions and forgive me but before thare
will be no clear policy on evaluating documentation as for Theming or Core or Contribs and that it takes 2 weeks almost to discuss if a doc-page that seem not to accomplish the proposed task to help out newbies should be modified or even deleted I'm very pessimistic at the moment.

:-(

I personally also think starting a new empty "consolidated" theming book is a good way to go, but I'm afraid that merging all the current existing pages pertaining to theming in one is such a large project that it will take a lot of time, and during that time we've added yet another place that people will have to look for this information.

The "conceptual vs practical" distinction is an important one, but not one with clear edges. I personally will NOT just follow a step-by-step or copy and paste a snippet into my site without first understanding what's going on, as much as I can. There are so many inter-related variables with Drupal I don't think it's practical to imagine people are going to contribute such detailed step-by-steps to cover all contingencies, and I think it's very important to teach the noobs how to fish rather than in addition to just dishing out the bouillabaisse.

Another point - AFAIC the project is merging the existing pages into one book, and it's already a huge one. We're not talking about writing a whole lot of new pages; at best a good information architecture will provide logical places to put, and therefore encouragement to write, new material.

So yes, I do think the primary navigational structure should allow people to find what they're looking for if it exists. If what they're looking for is a step by step cookbook, and it turns out not to exist, then the place where they're looking should then give them a good conceptual framework of background information, guidelines/pointers/hints to be able to figure it out for themselves.

I don't think the two types of information should be in different books, or even in different parts of the theming book, again because there aren't clear edges to the distinction - many good "step-by-step" pages contain useful conceptual/foundation/background/reference information, and a page intended to fit the latter type may well contain exactly the snippet you're looking for as an example.

The specific tasks you're talking about are so many and varied I don't see how they can be used to structure navigation - they need to be grouped within a well thought-out conceptual hierarchy of topics.

Therefore I come back to the idea of a "main backbone" set of pages, which I do think should be oriented conceptual/foundation/background/reference type pages, and then the specific tasks, with the related howto's snippets etc relating to that topic are listed in sub-pages below tagged by version applicability.

You first have to figure out who your users are, then determine the types of tasks they have to do, then give them specific instructions on how to do it (and make it as procedural as you can).

If, and only if, they need some theoretical information then you give them the absolute minimum that
they need to complete their tasks and only at the point where they need it for a particular set of tasks. I'm not just making this stuff up or saying it because it happens to be the way I've always done it. According to all the research and user-testing I've seen, this is the approach that works best, that users prefer, and it's almost universally accepted as best practice (although it's rare to see it in the open source world where most documentation is done on an ad hoc basis and developers do much of the writing).

This doesn't preclude having any amount of text that goes into excruciating detail on theory and concepts but it should be pushed well out of the way so it doesn't confuse and distract people who are just trying to get a job done. Sure, if there's a bit of conceptual information that they need to execute a particular set of tasks, then it's absolutely got to be there but if I push education on someone because I think it's good for them, or would make them a better Drupalista or a better person, it's simply patronizing and leads to distrust ("He made me read all this stuff as if I needed to know it but then it turned out I didn't need to know it all for what I was doing!")

I absolutely agree with what you say about teaching people how to fish. I just happen to think the best way to do so is always by providing step by step information (tie hook to string, put worm on hook, throw hook in water) rather than conceptual (Fish are aquatic vertebrate animals that are typically ectothermic, covered with scales, and equipped with two sets of paired fins and several unpaired fins.)

People learn faster and better when they are successful. The best way to help people to be successful is for the writer to understand what it is that they want to do and then tell them, using the fewest possible words, exactly how to get it done.

@LeeHunter

- Thanks very much for your very very simple explanation. I really appreciate and understand it very clear.
This is exactly what I was looking for. Thanks

Here's a straw man TOC. I'm not suggesting this is the perfect way to structure the handbook especially since I'm definitely a theming noob so I may have got things pretty confused but, speaking as a user, this is the kind of doc approach that I would find most helpful. I'm using a fairly standard documentation model where each section has a brief overview followed by procedures (overviews contain no procedural information, and procedures provide no conceptual information). :

1. Introduction: Who should read this guide, brief non-technical definitions of theme and theming, brief explanation of what the guide contains and pointers to other documentation (e.g. developer's handbook)
2. Working with theme files: Brief overview that explains that there are two main locations for theme files and the importance of copying files to a renamed directory. Mention that the reference section has detailed information on the types of files. Mention that there is more information about files in the section on overriding module output. Provide a step-by-step procedure for creating a theme based on another theme. Provide a step-by-step procedure for setting up the files for a new theme
3. Specifying the layout and presentation : Brief explanation of the role of CSS in theming. Mention Firebug. Clarify that this section only covers how to apply CSS to Drupal output whereas altering the output (renaming classes or creating new divs and classes) is covered in a later section. Brief explanation of the concept of regions. Provide a step-by-step procedure for specifying the regions. Step-by-step procedure for adding a CSS file to a theme.
4. Customizing a theme for specific pages or sections: Explain that individual nodes, pages, sections can be themed differently. Step-by-step procedures for theming the front page, theming a specific node etc.
5. Overriding module output: Explain that modules often provide files which can be copied to a theme. Step-by-step procedure for adding the module files to a theme. Step-by-step procedures for overriding output from each of the core modules (especially the common ones like log-in and search)
6. Working with variables: Brief explanation about what a variable is and where they come from. Explain that a theme can make use of variables from different modules. Mention that the Devel module should be installed. Step-by-step procedure for discovering what variables are in a module. Step-by-step procedure for turning a variable into themable output.
7. Reference: This would be the bulk of the current D6 theming guide.

OK I kept quiet for a while hoping others would jump in, and in the meantime have started using tools to do the electronic equivalent of Lee's

The only way I know how to do a big restructuring/consolidation job like this is to actually print out every single page and see what you've got.

I'm using Evernote to capture the pages, not only to save the trees but it's a much more effective tool than paper, IMO an excellent tool for any sort of note-taking/websnippet capturing and a model for hierarchical tagging for other software to emulate, also excellent full-text search.

Of course everyone's going to come up with a different outline - I plan to start out devising my proposed structure by working from the bottom up rather than the top down, classifying the various pages pertaining to Theming in a way that I think makes sense to me, different Vocabularies for the different "doc properties" factors. Only when that's done will I attempt to come up with a single topic hierarchy for the "primary navigation spine", based on roles and tasks as much as possible, assuming we're going to continue to use something like Book (but hopefully combined/supplemented with robust tagging/Views and much better search).

This project really needs a tool to allow people to show the same content with different prototype navigation schemes so the community can give feedback (vote/ratings?) and hopefully come to a consensus. In the meantime it should incrementally improve users' ability to navigate the haystack without disrupting the status quo until a much better design is determined.

I'm thinking a separate site with "stub pages" without the d.o content but simply containing links to its pages (iframe/Lightbox display?), along these lines , but obviously it needs to be maintained as new content is added, perhaps even re-tagging for significant edits (I'm telling FF extension Update Scanner to monitor the pages as I capture them into Evernote). Big job. . .

Ultimately I think such a prototyping site should allow different Vocabularies ("outline A", "outline B" etc) to serve as the primary navigation (emulating Book) and in the meantime also serving as a "meta" resource for users - no actual content there, just helpful schemes to help users find what they're looking for, with successful strategies eventually migrated over to d.o. Bigger job. . .

@Lee I completely see your point about procedural as distinct from conceptual, and agree with you that the "main spine" topic overview node should be kept reasonably brief. However there are some special factors here that prevent this ideal from being consistently realized on d.o, at least anytime soon.

• IMO the project really needs a good tech writer/editor with IA experience to be put on creating/maintaining Drupal docs, ideally full-time and eventually more than one (OT I know separate issue of funding and oversight)
• In the meantime we've got hundreds of theming-related nodes in various degrees of (dis)organized context. These aren't going to be re-written for now, IMO it's barely practical to just move them around into a better navigation scheme.
• This process will be done over (probably an extended period of) time by (maybe a half-dozen?) volunteers in their spare time
• during which time we don't want to make the problem (of things being scattered in too many places) worse
• Drupal doc needs are IMO closer to those of a programming language than those of an "application". Teaching someone how to use PHP and MySQL could not be completely structured by granular task - they need to master a lot of conceptual information before reaching the point where they could get a procedural on "building a shopping cart". Of course there are app-like aspects, especially on the sysadmin side, and I do agree that user roles and tasks should as much as possible define the primary navigation structure.
• However I very strongly disagree with your putting all the "Reference" material in a separate main branch of that structure. IMO the conceptual information, even if it's not strictly prerequisite to the procedural nodes, needs to be located quite close to them. Thorough tutorials are a mix anyway, and a good conceptual doc should have examples that may prove to be exactly the recipe someone needs. Currently most nodes are mixed anyway

As an example, "displaying Primary/Secondary links from a single menu in a horizontal nav" (maybe not the best example, just one at hand from my recent experience). This is a "leaf" if you like, the only thing lower would be (version-specific) "here's how it was done before PHPtemplate", "here's how to do it in D4 and D5 except for Zen", "here's how to do it in D5/Zen and D6" and "here's how it's likely to be done in D7". And perhaps (skill-level specific) "totally easy way for newbies" which involves selecting a version/theme combination that has all this already set up good to go, if that happens to be an important enough criterion and they're early enough in the build process to have this flexibility.

As another example, there will probably be a "theming navigation" section in the "middle" branches that will contain both this and "displaying a context-sensitive Secondary menu when Primary and Secondary menus are separate", and "displaying only a primary in the horizontal nav and Secondary and lower levels in a sidebar"

These types of "task branches" will be able to contain only a certain percentage (half?) of the probably hundreds of existing pages that are looking for a new home. The parent "theming navigation" page should IMO contain the background information that allows a user to understand what they're doing, because the specific thing they're trying to accomplish will most likely not be exactly matched by a step-by-step recipe. But having all the related examples in one place along the background foundation information will make it much easier than it is now for them to muddle their way to a solution, asking more informed questions in forum/irc/mailing lists.

Bottom line - the conceptual information "about Primary/Secondary menus" needs to be close by, mixed in with the procedural cookbooks, but perhaps tagged for filtering by Views/search. The conceptual and procedural both need to be subdivided by version but closely together all under the relevant role/task parent, so the user is empowered to fill in the many gaps that will exist and be able to learn to fish if the dish they need isn't sitting right there ready to eat.

So IMO we need to work from both directions - come up with the upper levels of the structure (top down) and categorizing the tasks (bottom up) in order to arrive in the middle.

We already have "theming" at the top. That's a start, although in my opinion it's not great, because it's jargon that doesn't have much meaning to the newbie. In my opinion very near the top should be a division that distinguishes between "displaying content" (messing with the PHP that generates displayed content from the database) and "styling display output" (things you can do with just CSS). There may not be much already in the haystack that will fall into the latter category, but obviously this section would be more immediately usable by someone just getting their feet wet, who would freak out when first looking at template.php. However there probably aren't many other factors that have such clear dividing lines.

Sorry for such a(nother) long post.

sorry typo changed the name

While I'm here any doc teamers have a look at Diigo yet for "meta" commenting on d.o without actually entering new content into the handbooks or issue queue?

#332021: Choose a "social annotation" web tool for doc team's use

However we structure this document, there are some basic documentation principles that have to be observed.

Know who the audience is, understand exactly what it is they are trying to do, group related tasks together, give them as much information as they need to get the job done, and don't give them information that is not immediately useful for the task at hand.

I'm thinking that the audience for the theming guide is comprised of three distinct groups:

- Graphic designers. These are people who are responsible for specifying the page structure, layout, colors, fonts, and other graphic elements. From the theming guide they need to know how to work with regions and how to add their style sheets to a theme. In general, graphic designers do little or no coding (there are many exceptions but that's not relevant to designing this guide). Their domain knowledge consists of visual design and the use of CSS (or at least the ability to use something like Dreamweaver to create the CSS)

- Information designers/architects. These are people who are responsible for specifying how information is presented to the site visitor (just to clarify, this is not content management). From the theming guide they might want to know, for example, how to change the default text in the search box, or they want a certain CCK field to appear and other variables to not appear. Their domain knowledge consists of the principles of information design along with an understanding of the site's business goals and audience. In the real world, this role is often played by a graphic designer or web developer, but for the purposes of the theming guide, it's worth breaking this out as separate group because doing so helps clarify the tasks that need addressing.

- Web developers. These are people who are responsible for developing and modifying actual programming logic. They need to understand the Drupal application architecture and the underlying technologies. This the only group that really needs to know what "phptemplate" is and why it matters. They bring a domain knowledge of PHP, MySQL and JavaScript.

In the existing theming guides, the first two groups are completely ignored. This is an extremely serious oversight because these are the very people who would probably most make use of the theming guide. The D6 guide even makes a point of saying, right at the beginning, "don't put howtos and snippets in this guide". To my mind, that's just another way of saying "we don't want to actually make this guide useful to the people who should be reading it"!

However we structure the guide, we have to keep the various audiences foremost in our minds. Perhaps someone can show me that a graphic designer actually does require an intimate knowledge of the Drupal application architecture before they can add a CSS file to a theme, but as far as I can see, this is not the case.

Lee, I completely agree with the principles you're outlining, but maybe we're talking about two separate phases, or even different projects.

AFAICT we're not talking about writing "a document", or even writing anything, just coming up with a better navigational hierarchy so that all the existing Handbook nodes scattered around in the various locations can be better organized.

As you point out in relation to the (relatively tiny) D6 guide, many of those nodes were written without any attention paid to these principles, but they still need to be relocated, largely without much editing in the first pass (big enough project just relocating them).

I've spent just a few dozen hours so far looking at theming-related pages recently with this project in mind, and (repeating from above) have come to the conclusion that designing "the ideal" new top-down structure from scratch isn't practical. What I think will work is for us (those willing to help with this project) is as follows

• to use tagging (as in taxonomy) to classify the existing nodes with whatever terms we like, leaving them in their current location for now
• each team member should be able contribute their own tags, search for appropriate nodes on a given topic, etc
• therefore this needs to be done outside drupal.org
• over (hopefully not too much) time, we would strive to come to a consensus on the "primary navigation hierarchy" to structure a new Theming book
• the other classification matrices can be left as tags, and hopefully eventually these terms can be used in the source nodes on d.o.
• for the initial team tagging stage, I think Diigo is a good tool - other suggestions welcome
• for the second stage - demonstrating navigation hierarchy - I think the idea I outlined above of a "meta" drupal site using nodes that just link to the actual content nodes on d.o. would work - other suggestions welcome

I personally feel the only practical navigation hierarchy (for Book) is to base it on content topic, e.g. "theming menus". At the top level we can (in stage 1) try to fit all the "middle level" content topics under "User roles" as you propose here, but I very strongly feel if we do these need to be 1. few and 2. already clearly understood by the average site visitors - scratch "information architect" until someone (you?) writes appropriate (probably mostly conceptual :) content specifically for that area. If these terms end up just being taxonomy tags then of course these two points are less important.

Here are the top-level "role" classifications I think are workable, not just for theming, but for drupal as a whole:

• sysadmin - installation & infrastructure
• sysadmin - upgrade & migration
• sysadmin - operations & maintenance
• site-builder
• designer

Only the last two apply to theming, and probably "designer" would just get the "no coding CSS-only" topics, so categorizing the many "site-builder" tasks into a logical mid-level hierarchy is of course the bulk of the first stage in my above notes. Unfortunately, there will probably be many nodes for which

• no role applies

so it may not even be practical to use these for top-level structure, but again, that will come out during stage 1.

Obviously in order for any such exercise to have any validity we're going to need input from more people than just us two, so any interested "lurkers" out there, please chime in with your feedback and ideas. . .

I don't believe restructuring the theming guides would be that difficult. This is what I do for a living (I'm a technical editor and I've worked with doc sets as large as 10,000 pages) so I'm reasonably confident that it's doable within a relatively short period of time.

Phase One would only require consolidating content. This is mostly a trivial exercise and could be done very quickly (a few hours work at the very most):

• Change the title of "Theme Guide (Drupal 6)" to simply "Theme Guide". Leave the "Theme Guide (Drupal 5)" in place for the moment.
• Take the main theming howto and snippet pages: http://drupal.org/node/22803 http://drupal.org/node/206662, and http://drupal.org/node/45471 and make them into children of the newly renamed Theme Guide main page (this would bring over all their children as well). I'd put a new page in their old location saying "For theming howtos see .." or "For theming snippets see ...". Over time, the theming howto's and snippets would get reorganized into more relevant headings, but this at least gets them into the guide where they belong.
• Move any other theming-related howtos or snippets etc not in the above sections to the generic Theme Guide. Also move stuff like this page on contributed themes: http://drupal.org/node/196218/

There are probably some more pages that have to be moved and it still doesn't give us a good structure, but it doesn't disrupt anything and it brings the bulk of the theming-related content to one place, which would be a major achievement. It means someone trying to find theming information won't have to look all through every part of the Drupal docs to find what they need.

Phase Two is a bit more challenging part because it involves merging the d5 and d6 guides. Some of it is easy, for example the section on updating themes doesn't even belong in the d5 book anyway because it covers everything from d4 to d7. That section should actually be moved immediately. There are different ways of doing some things (e.g. defining a region) and structuring files between D5 and d6 so those chunks have to be carefully identified and marked with appropriate headings.

At the end of Phase Two there is one and only one Theme Guide. Everything to do with theming can be found in this guide (hallelujah!). It still lacks a sensible structure but it's no worse than currently exists and the fact that everything is consolidated in one place would be a giant step forward.

Phase Three involves shaping this relatively large guide into a more coherent structure. This would take longer to accomplish, but (once we've decided on the right TOC) it could be done incrementally.

Does that sound like a plan?

I was working on the assumption that we'd want a good structure framework in place before starting to actually moving the chunks around.

However if that's not considered important, yours sounds like an excellent plan. Obviously, once all the theming nodes are together in one book we'll need to be careful about the re-structuring, logging properly etc, AFAICT there isn't any diff-style history record for relocations.

So if it's that easy, why not just move the D5 book over from the get-go, bump the D6 one down a level, e.g. starting point to the working structure:

Theming guide (currently D6)
-current D6 content
-D5 book
-snippets
-howtos
-misc working (for other stuff)

Regarding the volume of work, you've got more experience, but I see the community-consensus feedback process as adding a lot more to what it would take if just one author were involved, and the level of experience needed to parse out the version differences might be pretty high for some topics.

Perhaps a new component "version applicability" would be helpful for posting queries?

One type of theming related content that IMO can remain outside of the new book would be notes specific to contrib modules, e.g. http://drupal.org/node/295346

For now anyway; in an ideal future world it would display under an appropriate location in the theming guide as well as in the module's docs.

You're right, there's no reason why we couldn't consolidate the D5 book right away.

Re. having the structure in place first, yes I'd definitely like to have an ideal structure (table of contents) at the beginning, but I think it will serve us better as a roadmap of where we want to end up rather than as the starting place to which we add content.

My reasoning is that there is major "low hanging fruit" in consolidating all the theming content in one place. For a fairly small effort, we save the reader from the madness of looking in five or more places for theming guidance. It will be a somewhat ugly TOC, but from there we can, over time, reshape it into our ideal structure.

If we started from the ideal table of contents, and tried to refactor the existing content, it would require a more sustained effort and I would think perhaps add too much pressure for a volunteer effort (it would take quite a lot of work before it's ready for public consumption) If were working on this full time and working towards a release date, I would actually start with the framework, refactor all the content and get everything right before it's exposed to the public, but that approach doesn't seem to suit a project where people are working on a more ad hoc basis.

sounds good to me

in fact I'd say the TOC should be off somewhere else, not relevant to 99.9999 percent of people coming, just docs team, start a new issue here?

Needs input from more than just us two though - c'mon themers speak up!

Addy?

Redesign question - possible to auto-pathalias books so handbooks (maybe even per book?) shows up under a given path?

site:drupal.org/handbook
site:drupal.org/handbook/theming

Would make googling much more effective!

You have spent alot of time with writing and debating. So much work and effort has gone into this, I trust your recommendations. Try making some mock-ups of your final recommendations. This makes it easier for the very busy people interested to grasp what you're proposing and then give sign off.

Other than that... Hmm.. how much of this can you simply "do" without needing consensus? You've spent alot of time and thought on this, and I think it might be best if you grant yourself the authority to make the decisions and run with it.

For which parts do you need add1sun's or anyone's direct approval?

Grant yourself the authority and do it. It's a do-ocracy. The beautiful part is, you can roll-back any changes. Go for it!

Am I wrong here?

Thanks for joining in Heather, welcome - also to the Diigo tag team!

Well I've posted an initial working top level that would get us started, but getting even to that point certainly needs higher powers than I have. In fact I don't even know how to consolidate separate books and branches from several books all into one. Might even require some direct DB import/export work?

While editing content and leaving it in place is less disruptive, my understanding is that major changes in hierarchy structure do need some level of approval if not consensus, if everyone just started shuffling stuff around as they saw fit I can't see it improving matters much.

AFAIK there isn't even any audit trail about location changes, at least it doesn't show up in the Revision tab.

It looks like this entire topic will be stalled until someone *with* the authority will grant a sub-team to be created.

I think the choice of Diigo to express the ideas in the above conversation would be ideal. These comments can be seen in situ and reviewed (without needing to parse the voluminous comments, back and forths of a threaded conversation).

Have you posted this proposal to the docs mailing list?

1) To create a sub-theme to *ZERG* the theme handbooks.
2) To use Diingo to build consensus amongst the sub-team
3) To deliver the final recommendations via Diigo to someone who is capable of implementing changes.

- Ideally, someone with those editing rights would be able to follow-along on the sub-team's efforts, if not be directly involved.

if you haven't already written to the Docs mailing list, then I'd be glad to!

Otherwise I don't see how we can get any movement on this.

I just thought maybe changing status will get a review on this page.

Thanks Heather maybe a fresh voice would help move things along

Sorry I haven't kept up on this I have been sick and traveling (ook). I'm on my way home now and I will respond more fully before tomorrow's IRC meeting. Thanks for putting all of your work into this.

For the sake of clarity, here's the current task as I see it (probably Addy's)

Proposed initial structure (just because it's easy - not to remain)

Book title - Consolidated Theming guide
-D6 book
-D5 book
-theme snippets
-theme howtos
-misc working (for other stuff without clear edges)

Task statement:

Bring all the current Handbook books and branches that deal with theming into a single Book so all theming-related content can be effectively re-organized. (pre-requisite technical issues to be resolved with d.o. webmasters and book-knowledgeable wizards, obviously we want to keep the node numbers and existing path aliases)

Note that much theming-related content isn't contained in clearly defined branches related to theming, they're all mixed up with other topics. These will need to ad-hoc moved on a node-by-node basis.

Hopefully Addy (and/or other site maintainers) will have the ability to do this in response to the sub-team posting issues, but ideally a person with such powers will actually be participating with the team.

Possible related tasks:

Give some feedback on the ideas already outlined regarding nav hierarchy structure.

Help get more people on the team and make it an "official" theme-docs sub-team

Check out Diigo and if appropriate give an "official" OK, encouraging the theme-docs members to join and check it out

Ok, so to reply quickly (sorry, I'm still backed up with work and fighting this damned flu):

I think doing a top-level reorg to get all of the contents under one book is a fairly straightforward thing and I can easily do that to get thing started. The main thing for that is we need to know is are we re-using an existing page for the top landing page or creating a new one? Moving things underneath in the new book can be done by anyone on the docs team, so no need for extra pull there.

My main emphasis for the time-being would be to simply consolidate everything in one book, into broadly sane places. We need to keep in mind that the redesign will be having an impact on organization so I'd like to proceed with that in mind. Basically, let's not do a ton of reorg work that will need to be completely redone again in 3 months.

Re: building a working group (subteam) I think that's a fine idea. You should email the mail list about what the group would be about and how people can express interest in participating. We can also put up a post on the g.d.o page with info about the group and how folks can get involved.

Diigo stuff I have responded in the other issue and I have joined up.

So, in summary, let's do it. Tell me what that top-level page should be and I'll set up the book and get the major sections moved under it. The theme working group can then continue the work. If I missed something big, just point it out. I'm not avoiding anything, just tired and distracted so prone to missing stuff. :-)

I just want to address one comment here

In the existing theming guides, the first two groups are completely ignored. This is an extremely serious oversight because these are the very people who would probably most make use of the theming guide. The D6 guide even makes a point of saying, right at the beginning, "don't put howtos and snippets in this guide". To my mind, that's just another way of saying "we don't want to actually make this guide useful to the people who should be reading it"!

Your assumption is wrong. It is also very dismissive of the ONLY volunteer at the time who wrote stepped forward and wrote the Drupal 6 them guide when I asked for help. It was written by a web developer, for web developers because no other discipline could be bothered to contribute. The reason it was written as a stand alone guide was that the intermixing of content in the existing theme guide was covering versions 4.5 though 5.0. It was also a vastly superior document to the confusing array of information that had orgainically grown across various generations of Drupal releases and types of theme engines.

My goal was always, get content on there. It can be edited, consolidated and updated ONLY if it actually exists and not if it is just endlessly discussed.

There has never been a barrier to re-organization/consolidation if someone volunteered to step forward, present a plan, discuss, revise, implement. I realize that you 'can do better' and I wish you well, but please be aware of the harm various phrasing and assumptions do to the people who worked hard to contribute before you.

I hope that clears up any confusion and assumptions of the previously contributed work by the volunteers that came before.

Sepeck +1 on all three:

tone/phrasing issue
the tremendous value of dvessel's contribution
waffling on vs getting productive work done

Getting a group to agree take a lot of time and energy, and sometimes just isn't practical

but on structural/navigation issues I think at least trying is worth it, and more important than when discussing per-page content editing

Starting a new thread here

Hello everyone, I just noticed this issue and wanted to add that I'm glad that there's a lot of focus and attention on improving the handbook. As sepeck already mentioned, when I started with the theming guide in 6 I was concerned with having so much content and loosing focus for the end user. I'm aware it's not for everyone. I went for the conceptual in the hopes of getting more people on board with the underlying knowledge of how themes work. This is what helped me improve my theming the most but yeah.. Others who just want to get things done with tutorials and snippets will leave feeling frustrated.

The note I added about not adding howto's and snippets was placed because I felt in most cases, user contributed snippets can bring more confusion. There are countless ways to go about but we don't need the nth iteration of some far off corner case. That's not to say that I'm against it completely. If it's to illustrate core ideas, I'm all for it. The note I made stated this explicitly. Not how to add another clever way of doing something to fill a very specific need unrelated to core.

I feel very strongly about this. Easy to follow and concise tutorials I'm all for but let's just be clear that there should be some limits placed on what should be in the handbook or it'll grow out of control.

dvessel - excellent point on clutter and chaos, but seems to me to go with the territory of user-contrib docs, there's no question it takes a well-thought out IA to make the navigation (in this case one topic-based hierarchy) usable, as well as ongoing maintenance to keep it that way.

Unfortunately it takes some judgement to decide what is fundamental and significant and what's an edge case, and the line doesn't have hard edges, it's a continuum. Ideally there would be some sort of rating/voting system in the future (user Flags?) to help float the former to the top and drop the latter to the bottom in a given View.

I feel very strongly that the conceptual overviews, the howtos and the example snippets should all be together in the "by topic" branch of the Handbook rather than having these "documentation type" branches higher up, and my understanding is that's the way we're going in the re-organization.

The way it's been organised (by doctype up above, topics below), we've kept this one corner of the Handbook nice and tidy, but not as useful to all as it could be, and having the various types of same-topic theming docs in different, widely separated locations in the hierarchy has just let entropy get out of control over the doc set as a whole.

Suggestion - Perhaps under the intro/overview of a given topic (e.g. page templates) if there are a lot of nodes that fall under one "documentation type", e.g. HowTo's, Snippets, they could then be classified between "mainstream" and "specialized"?

For those topics that don't have so many (e.g. comment templates) then there would just be one flat Snippets branch, or if the total pages across all doctypes were small, they would all just be sub-pages of the intro/overview.

Feedback and other ideas welcome.

I feel like I'll just be adding another voice to an unsolvable disagreement. I see dvessel's point- too many use-bases and examples might amount to white noise. on the other hand, an example is a valuable learning tool, which a new user could apply and try out.

If you're curious about how people learn- this is backed up by research (please don't make me get the citation)- when teaching, you are better off demonstrating one method that work, and later introducing alternatives. for example, if you were going to teach cutting and pasting in a document editing program, you could show the learner the right click content menu, the menu system and the keyboard short cuts. however, if you're teaching someone new to computers you're better off teaching ONE method, one model to begin with. this lightens the cognitive load. remember, they're still getting their heads around the concept of a clipboard, the entire environment, etc.

choose one method to demonstrate whatever theming concept it is, and then point advanced users to 'see alternatives' and have these alternative available.

I also want to add a point, that we're heading into a big redesign on d.o, so some of this may be moot.

(previously I posted this in Diigo)

http://www.disambiguity.com/drupalorg-redesign-a-strategy-for-the-docume...

I thought this was interesting - what i took away, leisa describes the thoughts of three users, their needs and their solution

1. i have a specific problem I need an answer to in which case, i search

2. i’m new at drupal, or some aspect of drupal and I need to get up to speed in which case, i need access to some ‘designed’ content (eg. tutorials) and I’m likely to hit the docs landing page

3. i need more information about which I am looking at now eg. I want to see the documentation associated with this module that I might choose

I think we should organise the theme handbooks to this end.

Answer to 1: Having all pages including relevant keywords, and keeping an index of all topics will improve search

Answer to 2: Create guided tutorials for specific needs. By modeling with a few examples we could encourage more contribution in this area

Answer to 3: Include "find out more" links or use tagging to generate lists of links to related topics

- It should be really clear what is guided tutorial content, and what is authoritative reference information.

Great points, and your last one raises a critical issues for the immediate project.

In theory "authoritative" (= confirmed as accurate?) is black or white, but in the current context (user-contributed content) it depends on the skill/experience level of the user-author-editors and/or the docs-team reviewers/organizers, which has a lot of variability.

For now best I could suggest is that the overview/howtos higher in the hierarchy contain or link to (IMO better - version applicability issue) examples that are both of mainstream importance and have been confirmed as working, while the "snippets" parent page within each topic area should contain a "try at your own risk" disclaimer, and we rely on author credibility and comments to assist docs-team vetting.

Or we look at a top-level division in the hierarchy of Authoritative (= written, or at least reviewed by those known to be topic experts) and Community, with the appropriate disclaimer. Content could be moved from the latter to the former by appropriate docs-team members.

Personally I think in future this would best be solved by rating/voting, or user-based Flags, but that's a redesign/infrastructure issue.

I'm definitely in the camp of give one or two solid examples with the main text and then keep "related snippets" all in one big bucket with a disclaimer. I think splitting snippets out into categories like "mainstream" and "specialized" is asking for trouble and more work than its worth.

I also want to point out that at some point we are likely to encounter "snippets" that could fall in more than one topic (i.e. you have to do two things under different "topics" to get the full snippet to work). Perhaps if a "snippet" straddles more than one topic it should be made into a "general" theme HowTo.

choose one method to demonstrate whatever theming concept it is, and then point advanced users to 'see alternatives' and have these alternative available.

This is exactly what I had in mind. The note I posted about not adding howto's and snippets not related to core also noted that it should be linked from those pages when relevant. This just happened two days ago. Textplease added a snippet unrelated to core in the preprocessor page and I encouraged him to revert it. In the end, it was linked. The link doesn't stand out too well but that's another issue. If we standardized on this practice or had it automated somehow, it would be great.

Short and focused tutorials I'd love to have in the main outline. The others can be linked.

Just two comments

1. Newbies that are not confident with filtered searching before they give up, last they will search for an "Index" page. Like @add1sum reported in his 1. answer :

Having all pages including relevant keywords, and keeping an index of all topics will improve search.

2. In the new redesign, thanks Markboulton Team the INDEX and I find that further ordering and structuring any Handbook sections should consider this fact.

I was looking for creating or convincing any one on Drupal.org this for a long time ago.

Hope this is the right place to post (or should I stickynote this somewhere with Diigo?), but are there plans to have a 'Building a Theme' section in the new Theming Guide? A few of dvessel's pages seem more directed towards folks constructing a theme from nada rather than tweaking an existing one etc so I think it would make sense to separate them out.