I've started work on updating the theming guide for Drupal 7. So far all I've done is rename the "Drupal 6 Theme Guide" section to "Theming Drupal 6 and 7" (and renamed the D5 part to "Theming Drupal 5") and made a few minor changes. What I'm hoping is that we can just add notes to the existing D6 content rather than fork everything.

One of the big chores will be to go through the 40-some items on the d6/7 theme update page http://drupal.org/update/theme/6/7 and make sure they've all been reflected in the documentation. Since there are so many items on this page, I was thinking we should make discrete notes right on that page so we don't duplicate efforts. For example, on the one bit I've addressed (http://drupal.org/update/theme/6/7#specify-all-css-js) I've added a note at the end like this: [docs updated]. Hopefully that will help other people to know what's been done and what hasn't.

Comments

psychopath_mind’s picture

Status

Until the docs are updated it would be more helpful to have it more prominent on TOP.

[U] Docs Updated
[I] Issue
[E] Error

murtza’s picture

kindly let me know if i can play a part in ur work. i m very much thankful to drupal documentation team cus i learnt alot from this section but most of the time i felt its not organized the way it should be. i just need to know that how can i help you? what should i do? i cant write articles cus english is not my mother tongue.

laura s’s picture

Title: Update theming guide for Drupal 7 » Create and update theming guide for Drupal 7
Component: Outdated » New documentation

I'm changing the title of this issue because what's really needed is a separate Drupal 7 Theming Guide. There are just far too many changes to try to add them here and there under http://drupal.org/theme-guide/6, and a bunch of new Drupal 7 theming goodnesses have no D6 analogue.

LeeHunter’s picture

Title: Create and update theming guide for Drupal 7 » Update theming guide for Drupal 7

Isn't theming in Drupal 6 and 7 basically the same?

As far as I can see, there are quite a few minor changes but nothing that couldn't be accommodated by a few extra pages to the D6/D7 guide. Or in the case of minor differences, just a few lines on the same page (in Drupal 6 do this, in Drupal 7 do that).

If we do a separate guide, it means we'd have to fork all of the existing content and forked content is a *seriously bad thing* for documentation because it makes the content unmanageable (e.g. people start making changes to one set and not the other).

I'm not saying that it should never be done, but it shouldn't be done lightly.

When the new docs.drupal.org gets rolling (later this year hopefully) we'll be able to do single sourced D6 and D7 versions by simply tagging content. In the interim, we should do what we can to avoid forking content.

The first step is to update the existing guide and create new pages where necessary.

arianek’s picture

lee - i imagine this explains a large part of the reasons laura suggested this http://pingv.com/blog/a-peek-at-drupal-7-theme-system-changes

i agree forking versions can be full of difficulties.... but it might be worthwhile in this case, as it sounds like there have indeed been some significant changes. at the very least, if we *don't* fork it, we'll have to have some additional D7-specific pages to accommodate some of this info.

LeeHunter’s picture

So far I haven't seen anything that can't be accommodated in the existing guide with much less effort.

If there is a section or two that's radically different from one to the other, we can always just refactor the content out into D6 and D7 subsections within the guide. It's not exactly ideal for the reader. They should have the option of seeing version-specific content but that will have to wait till we get a better toolset to filter by version.

Also I think it's important to note that the content for D6 (i.e. stuff that's still totally relevant for D7) still has significant gaps. If someone goes in and fills those gaps in the d6 version they'd have to do it in the other and realistically that just doesn't happen. That's why single-sourcing is such a fundamental best practice for technical communication.

arianek’s picture

ok, if you think it can be accommodated that way, then i'm all for it - until we have proper versioning, it is certainly easier to maintain.

laura s’s picture

I can see the concerns about splitting up documents, but really, what the intermixed guide says is RATFM - read (all) the effin manuals, and plow through all the irrelevant stuff or get confused. I see D7 as about as much of a new theming system as could be without changing the theming engine. 50+ changes are not "minor".

And what about the front-end developer new to Drupal and starting with Drupal 7? Are they to have to learn Drupal 6 theming and then go through all the upgrade changes?

Maybe the tools are inadequate here, but that doesn't mean intermixing theming for two rather radically different APIs is a good idea. IMHO.

LeeHunter’s picture

As far as I can see, many of the specific changes are indeed minor and a number of them have already been made in the text. For example, in this page about overriding stylesheets http://drupal.org/node/263967 the information is the same (as far as I can tell) in Drupal 6 and 7 but a little note was needed to clarify that D7 needs to specify the stylesheet in the .info file). If that's the only difference, it makes no sense to fork the whole page. Many of the 50 changes are on that level of significance. Yes there are several very significant changes but it shouldn't be hard to factor them out and highlight them.

Re all the irrelevant stuff that you feel the reader has to wade through, let's just identify those specific nodes as relevant only to D6. (eg. Working with XX templates in Drupal 6, Working with xx Templates in Drupal 7). That's a far better use of our time and energy than doing a wholesale fork of the entire guide.

It's not entirely a bad thing that a themer will see information on both in the same context, because many themers will be working with both D6 and D7 themes or converting a D6 theme to D7, so it actually aids understanding. However, in a perfect world it would be better if the reader had a choice of seeing only D6, only D7 or both.

In documentation forking content is a very ugly thing and something that really must be avoided if at all possible because it causes endless headaches and doubles the workload for editors.

laura s’s picture

In documentation forking content is a very ugly thing and something that really must be avoided if at all possible because it causes endless headaches and doubles the workload for editors.

The API forks every major release. Yet documentation tries to be backwards compatible. This is a mismatch. The most confusing manual is filled with conditionals. It may feel easier to maintain, but it's not easier to digest for n00bs.

LeeHunter’s picture

Yeah, I totally agree that it's not ideal but it's a question of balancing a number of relative evils.

On the one hand, you have the evil of text that is more clunky and verbose and on the other hand you have the evils of content that is incomplete, inconsistent and can't possibly be maintained.

The only way to do it properly - eliminating all evil from the world - is with conditional text (i.e. by tagging version-specific content with special markers). That way you get the best of both worlds: the reader can click on something called the "Drupal 7 theming guide" but what they're actually seeing is the one corpus of theming content only with D7-tagged content revealed and D6-tagged content hidden.

Unfortunately we don't yet have that capability.

But even if we were going to do a new D7 theming guide, we'd still be better off at this point going through the existing guide and making the changes ... and THEN making the decision as to whether the readability issue warranted forking the content. That way we'll still be fixing the Drupal 6 guide as we go and we can make a better-informed decision about what really needed to be forked and what didn't.

ctmattice1’s picture

Point in question.

I'm ok with some of the theming docs as a novice module developer, however FAPI is NOT my strong point. I can work through most of the D6 stuff but D7 is a royal PITA to figure out.

Now that we have bodies as fields #372743: Body and teaser as fields in core, the node module controls the form for bodies (mainly through wrappers to entity), and entity for fields . Even [#546608] seems useless. If I take the existing form for say "quotes module" I have to rip out the $form[body] or it no longer functions. Rip it out and the form works I can enter data, hit preview and all the relevant data from the form is displayed in the original edit form but not in the preview fields of the edit form.

When saved the page displays on the front page but not as the D6 version. When you click the menu url to the module, you get the breadcrumb but the remainder of the page just says "Array". It would be nice to get some docs in place so noobie's to FAPI (like me) can decipher whats going on. Since D7 has both nodecontroller and entitycontroller it might be nice to have docs for both types of controllers. I've read through the API's over and over, the module examples don't really help reading through their code either. The $view_mode agrument for hook_view I've read can be customized but figuring out how still eludes me. If there's some of these types of docs then it would really help developers. The upgrade docs hit on this some but still they lack clarity.

If someone would like to help me figuring out what I don't know then in return I can help write some docs to explain it with a little more clarity for noobs than I've found so far. DBTNG was a pain but not as much as forms. At present I'm seriously thinking about making a tpl file for quotes but to this point the emphasis has been on using hook_theme and module functions to control page generation.

I placed this in theming guide issue queue due to this is probably the first place module developers will look.

arianek’s picture

ctmattice - that's great that you'd like to help flesh out the docs in exchange for some coaching! i think the best approach would be to hop on IRC #drupal-contribute, and just say as much and that i sent you there, and ask if someone can help you out.

if you have trouble getting a response, feel free to ping me (arianek) for help.

arianek’s picture

Priority: Normal » Critical

Just looking at this again after months, the entire theme guide needs a 7 version or update. http://drupal.org/theme-guide/6 says it's 6 + 7, but 5 had it's own and since there are version numbers in the path, I'm not entirely sure whether it's more effective to keep 6/7 as a single section or split 7 off (I don't think much has actually been updated for 7 at this point).

Dear themers: help! Please review and update and/or ticket needed changes.

Bumping up priority to critical.

mlncn’s picture

Separate and backport anything that's been missed in the two or three years Drupal 6 theming has been stable.

Leaving 6 and 7 combined does nothing for the user of this documentation (most people working on a theme will be working on one version at a time). That should be what determines what we do, the experience of the people we're trying to help. For documenters, there's pluses and minuses, but personally having the combined version intimidates me from participating, because i would have to check anything i write about Drupal 7 in Drupal 6 to see if it applied.

Separating is a manual task of copying content into new nodes?

hansrossel’s picture

I'm also very much in favor of having a http://drupal.org/theme-guide/7.

To sum up the arguments:

- Too much has changed in D7
- A combined theme handbook for 6 and 7 will be confusing for new users.
- There was a separate handbook for D5 and 6, why not for D7
- If Drupal itself forks every release why should the documentation be backwards compatible
- A new theme guide for 7 offers an opportunity for a good rewrite
- After one year a combined 6 and 7 theme guide will be cluttered with legacy Drupal 6 code which makes it harder to add new and interesting new use cases and procedures how to theme in Drupal 7. Drupal 7 theming should be on top then.
- What will happen when D8 gets released? Will we then add again extra exceptions and "if" cases to the same 6/7/8 theming handbook that have to make it clear which parts are common and which sections are only for a specific version?
- http://drupal.org/theme-guide/7 is a nice and clear url to guide themers to

Anyway, it seems like D7 beta will soon be there, so this is getting urgent. I'm ready to start writing on a new D7 handbook, but of course this discussion should first be solved.

Jeff Burnz’s picture

+1 to #15/#16 - way too much has changed in D7 theming for this to be combined, they must be separate otherwise it will be completely confusing for users. I too would put my stake in the ground and say unless these are separate I am unlikely to participate. Having them together sounds like a good idea for an upgrade guide, but not the actual theme guide (totally different tasks).

mlncn’s picture

Compromise!

I have created a Drupal 7 Theming branch here: http://drupal.org/node/925532

For now, instead of exclusively using the book module to structure child pages, please put links in the body of the main book page. This allows child pages of Drupal 6 Theming to be tagged Drupal 7 also manually linked from 7.

If a page has changes that should be split out and you do not have permissions to make a doc page ping me in IRC: benjamin-agaric

LeeHunter has pretty much definitely contributed more to the maintenance of the theming handbook than those of us that disagree (certainly i've contributed squat) so let's step up here, and make the D7 version happen.

arianek’s picture

I'm not entirely sure it's actually going to save us work or be more friendly for folks looking for documentation by *not* just letting it be its own book section, but I spose go for it and do that for now.

If anyone is super confused and wants to work on the D7 pages, just toss them into the section Benjamin made and we can reorganize/link to later...

mlncn’s picture

I just copied over and updated one small page from the D6 theming guide to the D7 guide.

In the body of the D7 guide top node, i added links to the D6 handbook for some major broadly applicable sections:

It seems we should move a solid chunk of Working with CSS to a version-agnostic section of the handbook, and perhaps some general concept overview could do the same– but mostly i'm of the opinion that copying and revising for 7 is the way to go, we can even open issues here in this queue per-page and recommend backports of improved docs to the D6 Guide.

arianek’s picture

Issue tags: +theming

adding tags

add1sun’s picture

For now, I'm proceeding with just updating D6 pages with D7 changes (and adding new D7 pages where needed), as a bunch of work was already started in this way and so many pages already have D6 and D7 versions on them. I just want to get some work done quickly and frankly copying and updating into a whole new guide is more work right now than simply updating changes. In terms of the time we have *to get the essential info into the handbook* this will be much faster and simpler to note the D7 changes and make it a 6+7 guide. If people want to do a new rewritten from scratch guide later, then have at. I get the reader issue complaints but readers will be better of with docs that *exist* compared to a theoretical new guide that hasn't been written.

add1sun’s picture

I've removed the D7 section and moved/merged the content into the D6 book and renamed that to Drupal 6 and 7. We need to update the URL to be just theme-guide and put in a redirect for theme-guide/6 to that. That will be a separate issue.

arianek’s picture

Component: New documentation » Correction/Clarification

awesome :) thx addi!

and fwiw, i think if the path is going to get changed, it'll be more in line with the urls we started moving to during the redesign launch if it's something like http://drupal.org/documentation/theme/guide (no version # for now). dave or greggles or someone installed a path redirect module, so it'll automatically do that if we make a new alias for the page.

laura s’s picture

Ultimately we're going to need a separate guide, imho, as it's harder for new people to have to plow through both 6 and 7 just to get a grasp on what they have to do for D7. A merged guide is the ideal only for people who already know 6, or need to learn both. And even then, I find myself resorting to Solr to find buried documentation.

f people want to do a new rewritten from scratch guide later, then have at.

And with launch imminent, a distinct D7 theming guide is all the more important, imho. If history is a predictor, we can expect thousands and thousands of new themers coming to this project in the next year.

I have a lot of notes and such from blog posts and presentations to draw from for docs, but not having been privy to the recent documentation sprints and strategy discussions, I don't want to end up working contrary to the strategic plan. The 6/7 page is helpful (though has interesting gaps — did you know html.tpl.php is not mentioned or discussed at all outside of the context of RDFa?) but I'm not sure whether to post more edits there or to start working on some fundamental D7 theming docs as the opportunity arises. Thoughts?

LeeHunter’s picture

There are basically two big and conflicting pain points here:

- Users get confused and overwhelmed if they see irrelevant content (e.g. "If I'm working in Drupal 7, don't make me look at Drupal 6 stuff!")
- Docs people get confused and overwhelmed if they have to work with forked content (e.g. "Don't make me write/edit/manage the same words in many different places!")

The only solution is to follow technical communication best practices and use single sourcing techniques. In terms of the Theming Guide this would mean that:
- If an entire node is exactly the same in both Drupal 6 and 7, it gets mapped to both guides.
- If a node is mostly the same in both Drupal 6 and 7, it again gets mapped to both guides, but the paragraphs that are different are tagged as D6 or D7, allowing the irrelevant content to be hidden to the user (aka conditional text)
- If a node is mostly unique to D6 or D7, it only gets mapped to the relevant guide.

From the user's perspective, they would see what appear to be completely separate guides. But from the doc person's perspective, we only have one guide.

It's inevitable that we move in this direction (and the sooner the better) but unfortunately we're not nearly ready to do it for Drupal 7. We need a replacement for the book module (so that we can have the same node appear in different places) and we need some kind of technology for tagging chunks of text (and controlling whether they are hidden or displayed).

So for now it's a question of choosing the lesser of two uglies: Make it ugly for the reader or ugly for the docs team.

At the doc sprint last week, I think there was a general consensus that we just don't have the resources to create and manage two separate theming guides, especially when big swathes of the content are the same.

Aside from single sourced content, the other thing we're missing (again borrowing from the tech comm world) with respect to the Theming Guide is a doc plan. This is basically an analysis of existing and planned content that shows where the gaps are (html.tpl.php?), the topics that are no longer relevant, etc. That would allow us to break down the work into smaller tasks that people could claim.

But for now, it's an ad hoc effort so wherever you see gaps or problems, please jump in and make changes or additions. You definitely won't be working against a strategic plan. :)

arianek’s picture

lee's described the issue pretty succinctly here.

but we really do need help with it! i put a call out on the docs team group http://groups.drupal.org/node/94444, and it doesn't seem like there's many people who want to or are able to work on the theme guide right now. i'm totally not a themer, so i can't even begin to help with it.

any help you can provide updating the docs would be much appreciated. for the core module pages i've been generally structuring pages like:

[intro]
[info applying to both version]
[d7 specific]
[d6 specific info]

feel free to post on the g.d.o thread if you want to try and find others to team up with (or tweet to @drupaldocs and i'll retweet it)

Iztok’s picture

I can help with theming documentation.

I agree with LeeHunter and laura s about making separate D7 theme guide, because merged docs only works for people familiar with D6 and we got that info more or less from here: http://drupal.org/update/theme/6/7.

arianek’s picture

lztok - hi, we'd love your help, but making a separate guide for d7 isn't an option at this point. this is actually what leehunter is saying above:

"At the doc sprint last week, I think there was a general consensus that we just don't have the resources to create and manage two separate theming guides, especially when big swathes of the content are the same."

there are not enough differences to warrant two separate guides (at least until we have a way to single-source portions of the content rather than duplicating it, but this is a ways off yet).

for any sections that are similar, shared pages will work. if there's info that is totally D7 specific and not needed for other versions, then it's fine to make d7-only pages for that.

Iztok’s picture

Today I got a private message from a Drupal user asking me how to involve into Drupal theming documentation...

It hard to get started, and links from documentation pages seem to be outdated (http://groups.drupal.org/node/16594, from 2008).

I know it may sound weird, but for many of us not around from the start this is all very confusing.

sylvain_a’s picture

Hello everybody!
As a themer, i would like to get involved in the Drupal Theming documentation effort.

I've been scanning the theming book for gaps, but I guess working within the issue queue will be more relevant than editing randomly.
Especially since a lot of these pages are already meant to be moved/deleted/etc.
This is where a little bit of mentoring could be useful, if somebody is interested.

adellefrank’s picture

subscribing.

Shane Birley’s picture

I have some time right now, so, I am able to help out over the next few months.

arianek’s picture

Issue tags: +Sprint: May 2011

great - feel free to start anytime, and i'm hoping we can focus on this as one of the may sprint issues.

mlncn’s picture

Quite aside from what is best for end users (i think we have consensus that separate for major Drupal versions is better), i will say that i as an occasional documentation contributor cannot work on a merged document-- if i'm making a correction from what i observe in 7, i simply do not remember for certain what applied in 6 and cannot put in the time to check both at once.

sylvain_a’s picture

In case anybody missed it, this one will in the spotlight in May: http://groups.drupal.org/node/143419#comment-479924

Perhaps more theming-oriented people could sign in at the Docs topic sub-groups page, so we can be in touch more easily? http://groups.drupal.org/node/125669

rootwork’s picture

Just a process question: Does it make sense to keep putting theme-guide tasks on this issue? "update theming guide" seems like a pretty big task, and I'm not sure it makes sense to have it as a single issue -- apart from the good discussion around single-sourcing, like in #26 (in which case we should change the issue title).

To put this another way -- if I decide I'm going to start working on updating X section of the theming guide, and want feedback/review, should I:

- Post it in this queue?
- Post it as a separate issue?
- Post it as a separate issue and link to it from this queue?

Carolyn’s picture

I talked to arianek about creating several smaller issues and linking them here. The current smaller issues are tagged with theming and d7docs.

So if you mark new issues with those tags, you will see all the smaller d7docs theming issues from this link:

d7docs theming issues

arianek’s picture

I think this issue can be marked complete once all main/important sections have had D7 info added to them. Not necessarily needing to track any new theme guide work here, like you say, better off in smaller separate issues.

Gastonia’s picture

I just quickly scanned this thread as it's a bit long, so my apologies if Im off topic. If I am, please point me to the points that correct my understanding of the topic.

Having said that I think it's a tremendous mistake to not have a completely separate D7 guide. I'm a very experienced d6 developer moving to d7. I want to quickly understand the differences between d7, and I want to have concise, specific information for d7. I do not want to have to wade through d6 material to find minute tidbits in small italics about d7 sprinkled randomly.

I'm digging into my first real d7 project, and I've wasted hours not only looking for separate d7 information, but trying to discover differences. Is there a different .info structure? do I use print print $region or do I use render($page[region]) and whats the difference between the two? Do you know how long it took me to read through the d6 information only to finally find out that region[content] was required?

The questions I had earlier could have been quickly answered with better IA about d7. Instead hours are wasted, and according to the comments, Im not the only one having issues.

It's a failure on part of the Drupal community to not give d7 the full attention it needs by giving it its own separate theming guide. Now, before I get flamed, I understand it's a lot of work. I can't wait to do my part to contribute. But, until then I, and many others, are pulling our hair out trying to find out how d7 works so that we can contribute, and it's a shame that most of the quality content about d7 is outside the drupal.org website.

Blue

LeeHunter’s picture

The lack of a separate D7 Theming Guide is a symptom of an underlying problem which is that drupal.org is not yet set up to properly manage technical communication. Even with a full time paid staff it wouldn't be possible to properly maintain 6,000+ pages of content over three or more product versions when you can't do any kind of single sourcing.

By single sourcing I mostly mean being able to use conditional text and tagging to identify pages and chunks of text that are version specific. That way you can deliver what looks to the user like separate D6 and D7 guides without having to maintain separate forks. That's pretty much the way it's always done in any CMS that's geared toward documentation because even if there are resources to create the separate guides, it's generally not practical to keep the common content in sync.

There's a conditional text GSOC project (http://groups.drupal.org/node/149859) but I don't know when or if it will be integrated into d.o. It's a bit ironic really, that the content management system isn't yet capable of managing it's own content, but I guess technical documentation is a special use case that so far hasn't received a lot of attention.

arianek’s picture

Lee - that is the idea, I believe the conditional text will be applied to the Help system and (eventually) the online docs. Jennifer should be providing a more overarching update during or just after the conference.

pavelsof’s picture

Proposition:
To make a new D7 Theming Guide using the new structure proposed here.

Rationale:
-- Currently the documentation is badly structured.
-- A separate D7 Guide is needed (a lot of reasons stated above and I agree with these).
-- To implement the single sourcing technique on a Guide with better structure (i.e. D8+ theming documentation should not be based on the current structure).

LeeHunter’s picture

Status: Active » Fixed

Closing this issue, not the theming guide is fully updated for D7 but any remaining issues should be identified individually.

Status: Fixed » Closed (fixed)
Issue tags: -theming, -d7docs, -Sprint: May 2011

Automatically closed -- issue fixed for 2 weeks with no activity.