The current architecture that divides documentation by version number is completely backwards. For each guide there should be one up-to-date version in which any variations for previous releases are noted, perhaps as subsections.
For example:
Getting started
>Installing Drupal
>>Multi-sites
>>>Multi-sites for Drupal 4.7 and earlier
Multi-sites is actually a perfect example because there is a huge amount of content on multi-sites which is tagged as relevant for 5.x and even 6.x but you won't find it unless you look under "Drupal 4.7 and earlier"!
By having separate guides for each version, we're creating a vast amount of duplication (a big taboo in technical communication) and the docs for later releases inevitably lose a ton of relevant content.
This issue could also be partially addressed by single-sourcing content (e.g. tag the page in a way that causes it to display in both the 4.x release docs and the 5.x and 6.x docs) but I'm not sure if we're set up for that.
Comments
Comment #1
heather commentedChanged the component to reflect the new component categorization. See http://drupal.org/node/301443
Comment #2
johnnocadded tag
Comment #3
MGParisi commentedFixed with tags!
Comment #4
jhodgdonIs this really fixed? It looks like the original issue was stating that there are all kinds of duplicated guides around. That has not been fixed.
Comment #5
leehunter commentedChanged back to active. The problem hasn't been addressed at all. We have content that is equally valid for D5 and D6 (and maybe for D7) that is stuck inside a "Drupal 5" or "Drupal 6" folder.
Comment #6
MGParisi commentedAt times documentation simply ends with a version. Drupal 4 documentation is beign archived, and most documentation is either handled with exceptions or with a separate document. If the topic is handled completely different in D5 over D6 then a new document is created. If the D6 version only changes things abit, then the documentation can include exceptions. Ultimately it is up to the writer.
This issue deals with procedures to define when documentation should be separate and when it should be unified. This is not a simple procedure. I can not see a way to define a procedure that would cover all situations. Therefor I can not see any avenues for improved documentation other then adding a suggestion page to http://drupal.org/contribute of when and why document should be separate or when it should be the same.
The overall issue is when to combine multiple documents into one. A task that is just as daunting to define. However, if someone can suggest a solution, then I would be more then happy to listen, and even work on it with that person.
If a Drupaler has documentation suggestions, then another issue should be made or he/she could make the adjustments himself
Comment #7
leehunter commented