Some people might consider this a bug issue, but i think its better to make it a feature request. I find it quite confusing and difficult at times when reading the documentation to figure something out and then realizing that the documentation refers to a different version than what i'm using. This issue exists when reading outdated documentation for a newer version and also when trying to figure out issues for older installations with new/unrelated documentation. Since it doesn't always suite to upgrade to the latest version on production sites, i think it would be really helpful to have the documenation seperated by applicable version. Ideally the handbooks should follow the same cvs conventions of core and handbook pages should be updated/ported for new versions of core. Perhaps a good example of this is the system requirements page. Luckily someone has took the effort to include information about all variant versions. However, it would be better to know you are working on version 4.6 and look up documentation in the 4.6 version of the handbook. Perhaps a import function could also be included where if someone finds relavent information in a different handbook version, than can inport it into a different book and make any relevant revisions. I think some comments about this issue have also been discussed in the forums.

Comments

karldied’s picture

karldied commented
Status: Active » Closed (duplicate)

Note that handbook pages currently can show which version they apply to. See drupal.org/node/276, for example. This topic probably is more a matter of guidelines so that more pages get tagged with the applicable version(s).

Recommend closing this issue report to issue report /node/107953, Authoring Guidelines for placing/ organising v4.x and v5 documentation as a duplicate.

rcross’s picture

rcross commented

I was quite aware of the version tags that can be applied to handbook pages. However, I think this is not used sufficiently. For example, 5.0 just came out, but someone might have a 4.7 site or 4.6 site, and not be ready to upgrade yet. I think it would be useful to be able to look at the 4.7 handbook for solutions. Instead, the current solution is to read through what is there and then see whether it applies to your version. Plus, there is not very much backwards compatibility - usually, when something changes and is updated on the page the version number is usually updated as well. But the old information is then no longer part of the handbook. If the "old" page and the new page were both maintained (as would be best), it would seem silly to keep it in the same book since there would be a lot of duplication of content.

I think it would be relatively easy (and good practice) to be able to "upgrade" a book page in the same way that people upgrade a module when a new version is available. This would allow documentation to not have to be rewritten each time, but would still require it to be reviewed before assuming it is still applicable to all versions.

rcross’s picture

rcross commented

I would also point out, that this would allow us to also move to the often requested feature of downloading the handbook for a particular version of drupal.

rcross’s picture

rcross commented

Sorry for the multiple follow ups... The point that i forgot to word correctly is that of continuity in the handbook(s). The current solution somewhat deters the use of cross-referencing other material or expecting knowledge from another section of the book, since this may change in versions. Consider things like the user interface changes that people use. Creating a custom block might still use the same general ideas as previous versions, but a handbook page describing steps to do something will change due to the interface changes, even if the overall process is the same. There are lots of other issues that i can think of why having separate books would be beneficial. This might also be a interface issue, if there was an intuitive way to see the "version x book" consisting of just the book pages for that version, then maybe the current system could still be used.

karldied’s picture

karldied commented
Status: Closed (duplicate) » Postponed (maintainer needs more info)

The request is for a 4.7 version of the handbooks, separate from the 5.x version? Returning issue to "active" status.

Right now the guidance is for the on-line handbook to be integrated.

I suspect that a "frozen in time" pdf would be doable. However, to me this has the serious liability of forcing someone to look both at the old 4.7 documentation, and then the question isn't fully answered, at the current handbook. Especially since the current idea is to cover both the current version, and recent releases as well. I wonder if the real issue is that there just isn't enough volunteer people to keep a thorough set of documentation in multiple versions up-to-date.

The cross-referencing issue is pertinent. The doc writer's guide is updated to recommend updates to existing pages to help reduce link rot.

rcross’s picture

rcross commented

I guess there are a couple of issues here. Yes, being able to download a pdf of the handbook would be great but isn't the main point here. I think i mentioned this above, but this might be solved simply with some interface changes. I don't have a problem with a page being relevant to both 4.7 and 5.0 - but there is also a certain about of uncertainty when looking at the handbook as to how much the information is relevant to whatever version you are using.

For example, a lot of new people will be looking at the handbooks to install 5.0 - but alot of that information doesn't relate to 5.0 and I think its quite misleading and confusing to have that (unreleated) information in front of people. The caveat to that is that IF people know that it might relate but might also have some errors or inconsistencies, then i think that is ok. A new person should be able to go to the website and see only the documentation for 5.0. This would make things easier i think. It should also help enforce some updating/revision of the handbooks as well. At least if i'm reading the 5.0 handbook, then i can feel fairly assured that all this information has been updated/created to relate to my version of the code. It might help to consider this like a branch in cvs.

I will also put up the other usage case that I see, which is for production managers, legacy systems or something that are slower to update to the most recent version of Drupal. If they want to read some documentation to figure out a problem with their system, then its very difficult if there are supposedly newer features that you can't find. Even something as simple as a contrib module that might have some additional feature in 5.0 but hasn't been backported to 4.7. It should be easy to see documentation that only relates to 4.7 (or whatever release). Obviously i'm not suggesting for each minor release (ie 5.0 vs 5.1) just the major branches.

dokumori’s picture

dokumori commented
Project: Documentation » Drupal core
Version: » 7.x-dev
Component: Admin Guide » documentation

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

rcross’s picture

rcross commented
Project: Drupal core » Documentation
Version: 7.x-dev »
Component: documentation » Other documentation issues

this is still an issue for documentation

add1sun’s picture

add1sun commented

Yes, and it is still a hard issue. We are writing Getting Started guides per version now and if we can get a sustainable system in place for that, then we can probably extend that to other "core" docs like theme basics and dev basics. To make the entire handbook versionable in place is a huge technical challenge. I've begun poking at the Revision Tags module and related ideas to see what might be feasible.

Wolfflow’s picture

Wolfflow commented

FYI: related discussions:

More logical structure for Getting Started handbook
reorganize Theme handbooks
Proposal: Move all Drupal Multisite setup to an indipendent Section

gaele’s picture

gaele commented

Related issue: #328118: Drupal version switch similar to language switching block (actually I think I prefer the tabs at api.drupal.org)

+1 for rcross's idea.

Perhaps the underlying structure of the translation system could be used? It might be easy to start with e.g. a 5.x page, create a "translation" for 6.x by copying it, and build on that.

HansBKK’s picture

HansBKK commented
Status: Postponed (maintainer needs more info) » Closed (duplicate)

Very strong -1 from me

Here is the current text of the Authoring guidelines, born of long experience, and I feel very strongly these should have been followed all along rather than allowing the current muddle of version-specific books.

Version separation: It's generally better to have one page for all Drupal versions, rather than separate pages. Separate version pages are hard to maintain: when an issue is updated on the page for one version, it's often neglected on the pages for others. Separate handbooks for each version are impractical due to the amount of work; just one set of handbooks is difficult to maintain.

If versions differ substantially, separate pages are appropriate. In this case, organize the pages on the same hierarchical level, but include the version number at the end of the title, such as "Example topic, v. 5.x"

Right now many areas of the Handbooks are split like the OP is proposing, and valuable information that pertains to "past" versions (IMO current for many people) got moved wholesale to the "new version" book (say D6) and is no longer accessible to people looking at the D5 book. And conversely a lot of information is "buried" in the v4.7 sections that actually still pertains to more recent versions.

There should IMO be a single book by functionality area. Different levels of expertise and applicability to different versions over time should be dealt with via clearly marked sub-pages.

When we move from (say) D6 to D7, then those parts that still apply stay in the "central spine" of main pages, the parts that no longer apply get moved to sub-pages and marked as to what versions they do apply to.

The "drop is moving" much faster than the community resources willing and able to write docs can keep up, and I'm sure this will continue to be the case. It is very rare that the community will be able to do a wholesale conversion at any given point, the process has to allow continuous, relatively incremental updates.

Now if there were professionals (paid by Acquia or the Association?) on this full-time, or we were using documentation tools more suitable than Drupal+Book (gasp!) then of course these issues could be resolved differently.

and this is a duplicate of issues listed in comment 10

Wolfflow’s picture

Wolfflow commented

-1 for me. I have to agree with @HansBKK.

Different levels of expertise and applicability to different versions over time should be dealt with via clearly marked sub-pages.

It's much easer and simple to manage a Section with sub-pages for the different version and examples that may be provided by our members. I really wish we rethink this and establish a constructive and standard-management on archiving our documentation. To much valuable documentation is spread all over the Drupal Handbook without a simple structure of order as to facilitate our Documentation Team member daily work and support. So also to facilitate for newbies to find what they are looking for. Another point is also that every reader can much easy evaluate the documented materials and examples suggested for each version in one place.

HansBKK’s picture

HansBKK commented
Status: Closed (duplicate) » Closed (works as designed)

See http://drupal.org/node/254947 for related discussion