What to do with Drupal 5 documentation?

IMHO, a valid question and helpful to improve documentation quality. Sadly I have no good answer to this, anyone else thoughts plz.?

Outdated content can be placed in the "Archive" section. All D4 and early content is already there.

At the Vancouver doc sprint last December there was some discussion of whether we wanted to continue making EOL content available. It's a bit problematic because those nodes sometimes come up at the top of internal and Google searches.

Hi sorry Benjamin, really busy and haven't had a chance to follow up on this yet. Jennifer and I have been talking about when to cut D5 info out (aside from the upgrade 5 > 6 guide, which will remain up probably until D8 comes out?). It doesn't make sense to archive the D5 info yet because many people are still running D5 sites right now.

Some of the major core pages I've already taken the D5 info off of (such as core module handbook pages) - of course it's still in the revisions... but I think it'd be good to keep very D5 specific content up for maybe six months yet at least, while people upgrade sites...

Jennifer and I thought it would be good to contact Angie or Dries for input on this before making a ruling, and I haven't had a chance to yet, but will see if I can get some input asap.

Also re: where stuff goes... deprecated pages now go into the Archive book *and* are unpublished. There was far too much confusion mostly due to pages there turning up in google searches, so it's all retrievable but hidden from non-admin users.

I just pinged Neil and he thinks maybe docs should be kept up for 3 versions... so that means D5 would stay up until D8 launches. I can totally understand the need to support people on older versions... that said, we don't support code for older versions so I'm not sure if we are really obligated to support docs for older versions.

The online docs are a pretty big beast to begin with and I'd really like to start pruning, condensing, and making it less of a monster, and this would help. That, *or* in "dreamland" ideal situation, we'd get some kind of versioning for online docs built like there is for the API docs, but I know that's a huge job (not going to happen soon enough) and not going to address the immediate need for a decision on this.

Alternately, we could create a Drupal 5 Docs book and move it all there so at least it's not cluttering up the main docs.

Keeping documentation around for 3 versions seems wise --- users might need to look up how D5 works in order to upgrade their site to D6.

The upgrading instructions need to be kept -even from d4 and earlier - but that's the only documentation we should have for d5.

I seriously don't think it's a good idea to vastly increase the scope of the supported documentation by expanding to three versions. The sooner we get on with it and clear out that crusty old pile of d5 stuff the better.

Possible proposal:
- Pages that are multiple-version (D5, D6, D7, ...): Prune out the D5-specific stuff now. Usually the only difference between D5 and D6 is the navigation or some detail like that, and I don't think it's too much of a problem for a D5 site admin to figure out how to find the admin/xyz page, given the D6 and D7 information. Remove the D5 taxonomy term from the page as part of the pruning.
- Pages that are specific to D5 (aside from upgrading information): Archive to a special "Drupal 5 archive pages" book. These would be left published for some time period (a year?), or until some event (Drupal 8 comes out?) TBD.
- Add to the drupalorg module a block that makes it so that all pages in the D5 archive book have a prominent disclaimer box at the top warning people that they are Drupal 5 specific, archived, and will be going away (wording TBD).

I like the sounds of that Jennifer (and I'm waffling a bit, but think generally that if D5 isn't supported, it just isn't supported across the board, including docs).

I tend to agree with Lee on just keeping the upgrade guide up indefinitely (though there is no 4.7 > 5 one there that I can see, so it would seem they're not being kept up forever?) We should at least keep the D5 > D6 one up until D8 it out (or possibly longer 6 months after that.

The only thing in Jennifer's list I'd amend is to keep the D5 taxo up for quite a while, so that we can do a search for it and find pages marked D5 and weed/update them. So we might need to hang onto that for some time yet.

It's not at about breaking links for the sake of breaking links. It's about managing the content lifecycle in a way that balances the available resources (i.e. a tiny handful of people doing what they can in their spare time) against the reasonable expectations of the user community.

I'm not against keeping docs around longer or even forever but I don't think it's at all practical without at least two preconditions:

- Stale content *must* be hidden from normal searches (both d.o and Google) and from the normal docs view. The vast majority of doc searches are going to be for content relevant to D7 or D6 so it's a huge disservice to the reader if we show them results that only apply to D5. If we're going to make stale content available to people they should have to explicit indicate in a search that that's what they actually want. One of the big problems is that people can Google for something like "Drupal installation", for example, and the top hit could be the old install guide. To me it's far more serious that people are being shown the wrong content for the supported versions than people not finding content for a version that's no longer supported.

- Stale content needs to be presented with some kind of flag, like a box at the top, that warns the reader that they are looking at documentation for a Drupal version that is no longer supported, that the content is no longer maintained and that it may actually be incorrect. This would help minimize support requests.

RE #9 - I didn't mean we should get rid of the D5 entry in the taxonomy. Only that as we edit pages marked d5/d6/d7 to remove the d5 bits, we would at that moment remove the d5 tag/term from that page.

RE #10 - keeping old doc around and letting it be indexed by search engines is not helping the quality of docs. Part of what we need in our docs system is a way to search docs reliably. If old doc is returned by Google or our internal searches, then search becomes a less reliable way to find current information. We had that problem with the Archive book previously, which is why we did go ahead and unpublish the information in it.

I think this gets at the purpose of the on-line Handbook. I think it should be to have a quality set of documentation that people can find reliable information in, not to be a historical archive. We can export the archived/unpublished content if someone wants to maintain a historical archive, but I don't think that the documentation team wants to maintain a historical archive.

Ah, now I see that Lee in #11 said much the same thing. :)

I think we need to make sure that D5 handbook pages have links (probably at the top of the page really) to D6 and D7 handbook pages on the same general topics. This would help a lot when people land on D5 docs when they intend to find D6.

Also I think D6 and D7 theming should be split into two different trees altogether - with subject pages relating to both versions crosslinked obviously like I'm describing here. D6 and D7 theming are kinda different really...

hongpong - this is a much larger issue you're bringing up on how to manage versioning of docs pages. we're working (slowly) on a solution to that. ;)

----

all - i was talking about challenge this with one of my coworkers, and he had an interesting suggestion! it was this:

- a button/link is added to all pages that are tagged with version d5 (in the meta info block) that says "archive this drupal 5 content" (or something to that effect).
- clicking the button would clone the page, and send it to... a separate book? to a separate subdomain? something like that. then we don't even have to bother about hand separating the content (it can just take any d6/7 content with it, and if others want, they can curate the newer versions' content out).
- eventually as stuff got cloned out, we can really just remove the d5 content from all the main pages.

somehow we'd probably want to try and maintain the book outline, and we'd do this for each "archived" version - so we'd want to assume by the time we hit the next one, we're done with archiving any old content, so we'd only have to manage archiving one at a time.

this is all kind of a fuzzy idea, but i thought i'd get it out here, so that at least others could give input...

Hi, I am relatively new to Drupal and found this issue while searching for any plans to improve the interface of the Documentation. If there are other issues or discussions going on about this topic, I would be happy to know.

I completely agree with #11. I also agree that we should not delete or unpublish any documentation. We should just find a way to hide it from those who do not need it.

It would certainly be nice to have an exposed filter allowing you to see only documentation related to a specific Drupal version, and simply hide all content not relevant to that version. That way people also would not have to append strings like these to the titles:

• (Drupal 6 and earlier)
• (Drupal 7 and later)

To me it doesn't seem the right way to write such titles when we have modules like Taxonomy and Views to categorize and filter content.

We have a huge amount of good documentation about Drupal and contributed modules. But for a beginner it can be very difficult to find what you need, and it can also be difficult to know where and how to actually add new information.

Let me give an example. I don't know much about theming and template files, but yesterday I needed to find a way to display in the teaser only the first image from a CCK image field with multiple images. I googled "drupal cck theming" and found this handbook: http://drupal.org/node/62466, which is from 2006 and applies only to Drupal 4.7 and 5... And within that book there is even a page that apparently only applies to Drupal 4.7: http://drupal.org/node/71044. And this issue is about what do to with Drupal 5 content!

Later I found a solution to my problem (outside d.o), and of course I would like to add information about it on d.o, so that others can be helped. I think I could do that in one of two ways:

1. Create a new page titled "CCK for Themers (only Drupal 6)", and add my information there.
2. Update "CCK for Themers" to apply also to Drupal 6, and add a new child page titled "How to show only one image in teaser", and tag that child page only Drupal 6.

On http://drupal.org/documentation-writers-guide it is recommended to edit existing pages rather than creating new ones. But this can quickly become a complicated affair for someone like me with little knowledge of Drupal 4 and 5. I really don't know if the information I want to add, is also relevant for the previous Drupal versions... On the other hand, if I add a new page, we get duplicated content since:

There is currently a single version of the online documentation and many pages apply to all versions of Drupal.

In short, it is not always clear how to update documentation, and maybe this is why the information about such a popular module as CCK is very outdated? I think many cases similir to this could be found.

Here are some thougths I have about how to improve navigation and interface:

• Maybe move away from using the book and menu modules for structuring content, and instead use a hierarchical vocabulary, and Views module for displaying the relationships?
• There could be various filter and sort options: drupal version, audience, topic category, etc. Something similar to the options we have on the modules page: http://drupal.org/project/modules
• There could be an option to search for specific words or phrases in either title or body.
• Possibly a value for the Drupal version term should be required, so that when creating or editing a page you are forced to choose to which Drupal version(s) the content applies. Then, when a new Drupal version comes out, either the orginal author or someone else would have to either update the page with a few notes (to make it apply to more than one version), or make a completely new version of the page.
• We might consider having a separate page for each Drupal version. I understand this would lead to more work doing updates and maintaining different versions syncronized. However, I think it would make it easier for new Drupal users to contribute new content, and we would also avoid all those pages with version specific notes.
• Include the videos in the documentation hierarchy instead of having them in a special section.

These were my ideas, sorry for introducing also a few topics that not are strictly related to this issue, but are more general. If there is anything I can do to help, please let me know.

Hi Lars -

You should probably review #995362: Conditional Text ability needed for book pages and #995370: Want the ability to create multiple outlines/maps - they address 90% of your concerns and suggestions. The conditional text one doesn't really have someone dedicating a lot of time to it at this point, if you want to help out, that'd be great!

Hi Arianek, thank you very much for these two links. The first one also led me to Help System, a page about new features for Drupal 8. I will study everything carefully and see how I can help with all this.

fantastic! jennifer hodgdon (jhodgdon) is managing this infrastructure work so if you want to talk in more detail about how to help, you can often find her on IRC.

Echo what arianek said. :)

Much of drupal.org has the same issue; old, irrelevant content is getting in the way of people finding what they're looking for when searching. (Of course, testing and improving navigation is a big priority as well)

Inadvertent switcherooo

Unfortunately, D4 documentation has been archived and deleted for some time now. We where archiving all D4 documentation around 2 years ago (if it did not contain comments that would bring it up to date). This was discussed in IRC back then. In many questionable cases I personally dealt with, they ended up as issues (which I unfortunately did not follow during my break)

D5 is very valid, I would be running a D5 site right now if I did not loose interest. The problem is that the more documentation that exists, the harder it is to find documentation that you need.

There are many behaviors that naturally causes the phasing out of older documentation. I cant possibly explain everything I have seen but I will try to describe a few examples.

Example maintaining documentation for Views 1 & 2 for D5 and D6. Add Views 3 for D6 and D7, and the inevitable Views 4 for D7. Writing a single document to cover all of these possibilities presents the problem. Add to this that D6 requires CCK, and D7 does not, and that there are multiple versions of CCK and the problem starts to become even more complex. Then add another module like OG, that would use views, cck and multiple versions of Drupal and the number of combinations becomes very large

I am facing a similar issue to the above views issue while I continue to document OG. It becomes EXTREMELY tough to maintain D6 OG and D7 OG. If I am to write documentation that covers both versions, I would be handicapped in such a way that I would be unable to produce quality D7 documentation, or any documentation. I filed an issue, but after a week or two, I went ahead and separated the Documentation based on Core. This is in violation of the Documentation standards, but people needed D7 OG documentation right away. I made this decision based on the needs of the users in IRC. I was not happy with the solution, and there is still a document issue that is waiting for attention, but eventually, I suspect it will just float to the bottom of the queue. Its an extremely complex issue to solve in the book format.

Maintaining a Book Structure including multiple versions and combination of multiple modules is a good goal, but one that needs a new 3d type of book. One that does not just include core versions, but one that also includes module versions. This is a really interesting UX and IX challenge that should be looked into.

My experience in Documentation, and the many, many hours what actually happens is that this complexity is edited out slowly over time, making the documentation only valid for the latest few versions. This is either through many small changes or a large change made by someone who does not know the rules. I study revision history in making many decisions. The choices I make are highly researched and calculated based on Revision, Scope, Depth, Detail and comments...

Now I have probably closed around 5+ pages of document issues, and have worked on every document I have used that needs improvement over the entire time I have been working with Drupal. So some of the observations are seen over time, and with careful attention to details. It would be interesting to start providing a vote based feedback system for data collection to start to examine this statistically. There are so many docs its hard to navigate the book even after spending 50+ hours.

So I present another problem, when does the documentation become to narrow/broad in scope that it becomes more of a problem then a solution. Essentially the User Interface issues of too much documentation can handicap the entire document system.

I know these issues can be solved, and I will encourage/help anyone willing to go through the D.O. improvement process to achieve success in dealing with these issues. I am not one to sit back and shy away from work, responsibility or possibilities. My time is limited with other Document projects.

@lisa - what do you think about the idea from my coworker i posted a while back? http://drupal.org/node/1026542#comment-4097226

I love the idea of automating a way of archiving the content so it's not "getting in the way" of newer, more relevant content. Ideally, once a node is identified as 'to be archived,' that a second person with docs maintainer role or administrator approves it. We can just have a view of all nodes that need work done on them. That's pretty much what we're doing for the content audit. We're using Flags. Views are used to filter nodes from the "to be audited" list to the "has been audited list".

Also I would want to explore this in the context of greater d.o. / all book content.

Q: Once a node has been archived/cloned to another place, how do we show on the live node that it's already been cloned?

we could make the clone/archive link only display until it's been clicked, i'd imagine - and once the pages are in the archive, if anyone wants to maintain them and cut out the later versions, they can go for it. i'm not even sure it would need moderation, as i don't think anyone would go on a random cloning spree. ;) nothing actually gets deleted in the process, as deprecated pages would still be managed as they are now.

Is there a final decision on this? I just archived a few Drupal 5 pages in the Reference book about the old version of the Actions module because they seemed really out-of-date and likely to confuse people. Should I unarchive them?

Automating sounds like a great future solution.

Oh goodness, no we never did get this figured out. I am going to tag this with the infra tag, and I'm thinking it'll need to be re-evaluated due to the other changes.

Just brought this back up with webchick on IRC, and it seems that it's not worth doing something drastic here. Just keep marking deprecated and moving to Archive as needed.

If we want to improve on the problems with this, we could:

- Make D5 docs score lower for Solr
- Make a more apparent "Deprecated" icon/label

EDIT: Also, to note: Dries didn't want us to just remove all the D5 content as people still maintain D5 sites, and now that the docs are becoming "Community Docs" we don't want to be as heavy handed.

As things are now, we have a bunch of stuff in the Archive. Some of it is D4/5/etc., and some of it is just plain garbage. We went through with a query about a year ago and unpublished everything that had been archived, which effectively means no one can see it at all. Maybe we should rethink that decision and republish those items, so they can be seen?

Regarding searches - it's not just Solr. It's also Google/Bing/etc.

Regarding the more apparent Deprecated label, when the Community Docs redesign gets deployed, any page with the "Deprecated" status will show that in red in the page status area on the sidebar. But it would also be easy enough to put a label on the top of all Archive book pages to make that more obvious.

To add a "deprecated" tag to all D5 docs is, I think, something that could lead to confusion. There are still a number of people who have to maintain sites (e.g. those with a lot of custom modules that would cost to much to port forward) based on D5 and as long as there is not "better" documentation for a particular topic related to maintaining a 5.x -based site, the documentation, itself, should not be deprecated just because this is no longer a "supported version" of Drupal.

Are we planning to "deprecate" all D6-specific documentation in a couple of years? Given the number of sites still running on D6 and the likelihood that many of them are significantly complex projects which either rely on obscure modules (which may never be ported to D7 / D8) and/or rely on a lot of custom modules, I suspect there will be at least 100,000 D6 sites still in use, even a year or more after D8's official release.

To illustrate this: When D6 was released, there were 16,954 (reported) D5 sites. At the time of D7's release, this was about 12,088 sites, about a 30% decline. Now, almost 15 months after D5 went "unsupported", there are still 6,713 sites reporting they use some version of D5 (probably a lot more that don't report). This is about a 60% decline. If we project a similar pattern for D6 (I suspect it might be an even more gradual decline), there were about 355,000 sites reporting use of D6 when D7 was released. Current stats indicate about an 11% decline since then (about 315,000 sites on D6)... Assuming a 30% total decline by August 2013, that's still almost 250,000 sites on D6 when D8 is released. And 15 months later, assuming the decline is as steep as for D5 (which I doubt, since it's not, so far), that's still more than 140,000 sites using D6 in November 2014.

The dictionary definition of "deprecate" is "to express disapproval of". While we might no longer support the version of Drupal and no longer maintain the corresponding documentation (and a notice to that effect should be prominently displayed), using the term "deprecate" seems to imply that the information in these pages is no longer valid for people who have the task of maintaining an older Drupal site — this is misleading.

Just my 2¢… ;-)

I would wager this issue is moot now that docs team isn't formally maintaining docs anymore. I don't think anyone's going to spend the time weeding out and archiving D5 docs anymore.

Yeah... I think the answer for "what to do" is basically "nothing". We're not going to go around wholesale deleting Drupal 5 docs, tagging them as deprecated, or moving them somewhere else, at this point.

Right... sorry, this page just came up when I was searching for terms in another issue. My comments were more for "what to do next time a version of Drupal is 'deprecated'". If people still need to continue using that version of Drupal, I think the documentation should not get flagged "deprecated", unless it really is no longer recommended for the purpose intended... if the purpose is to maintain a D6 site (i.e. in a couple of years), we should not "deprecate" the documentation, but automatically display anything tagged just for D6.x with a prominent notice, e.g.: "This documentation refers to an unsupported version of Drupal and is no longer maintained" (and ideally provide links to a similar page that deals with D7 and/or D8).

Documentation of Drupal, imho, should never get "deprecated" if the only reason is that the version (of Drupal) is no longer "supported".