I have not been able to find guidelines on how to structure documentation for v4.x and v5. If this guidance is available great, and maybe you can point me to it? If not I'm making this feature request.

It will be useful to develop guidance, possibly in the authoring guidelines, on how to document features and changes for major releases. In particular this guidance would be very useful as V5 starts to get deployed and more documentation is created with that release in mind. Well thought-out guidance could help keep the documentation useful for readers as they use the new release.

Possible guidance might be one of:

  • existing content pages are updated with a "5.x" section to explain differences between v5 and v4.7.
  • a new page tagged "5.x" should be created for all pages that have v5 specific content.
  • all v5 pages should be placed in a whole new v5 handbook (well, maybe that's not realistic).

It would be useful to link to, with a view to consolidating, the discussions regarding how to structure the handbooks to make it easier for readers to get to v4.x or v5 documents. This feature is likely to be more in need as people begin to deploy v5.

Related posts:
Feature request on making documentation version-specific - http://drupal.org/node/105356
One example of the 4.x vs 5.x differences and questions about how to present - http://drupal.org/node/103915

Comments

sepeck’s picture

sepeck commented

In the past we've updated pages to be valid for the current latest release. Maintaining multiple versions docs has not been feasible due to a lack of volunteers. I will look at the guidelines again.

You will have to excuse the delay on the mail list and mark it down to the holidays, a new baby birth and one of the documentation teams major contributors being sick for the last few months.

vjordan’s picture

vjordan commented

If an opensource project can't take a breather to mark births, both recent and ancient, there'd be even less documentation contributors ;-)

It is likely to be important to keep 4.7 documentation for a fair while after the v5 release. There's going to be a reasonably big v4.x install base which would appreciate preserving the v4.7 documentation.

Maybe it's possible to retain 4.x (maybe just 4.7?) pages intact and produce a v5 documentation layer. Where the v4.x information is accurate for v5 maybe the v5 layer could connect to those pages. Where new information is required for v5 then link to new pages. I know little about how the book module works so I couldn't even guess if this is feasible.

Come to that, I don't know a whole lot about the extent of the v5 changes. If they're not extensive the documentation issues might be much less significant than I'm guessing them to be. And possible the guidance could be simple too.

pwolanin’s picture

pwolanin commented

For making a 5.x version of various pages, it would be nice to be able to copy nodes with more facility.
I already sent this as an e-mail to the docs list, but no one seems to have noticed:

2) Allow doc maintainers to more easily copy nodes:
http://drupal.org/node/106309#comment-186732

infrastructure issue: http://drupal.org/node/107721

karldied’s picture

karldied commented
Assigned: Unassigned » karldied
Category: feature » task
Status: Active » Needs work

The issue of copying nodes easier is probably better dealt with under a prior doc issue report at /node/107721 Allow documentation maintainers to more easily copy nodes which was just listed.

Regarding the topic "Authoring Guidelines," I've been working on a related issue, /node/110062 Update to Documentation writer's guide.

Per the suggestion here, the following pertinent sub-sections are proposed. This proposal is my perception of current guidelines and what the documentation team leader has stated. Also, my perception is that it is the most practical process. I put it forth here so the topic can be discussed in concrete terms.

...

Editing versus adding pages: Try to edit existing pages rather than creating new pages. It is better to cover a topic in one location succinctly, and then reference the topic from related pages. Editing existing pages rather than creating new ones also preserves links that reference current pages.

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"

Version designation: Use the "Drupal version" drop-down menu and select which version the page applies to. If the page applies to more than one version:

--Select all the versions which the page applies to

--Information on the page should be listed from newest to oldest version

--Mark the sub-sections for each version very clearly

--If the entire page applies to all versions selected, state so near the top, so that readers don't wonder what sub-sections apply to their version

Page length: Longer pages of several screens are acceptable. Use <b> or <strong> tags to provide sub-topic headings within the page. Very long pages should list the contents (preferably with links) after the opening paragraph.

...

pwolanin’s picture

pwolanin commented

In terms of making different variants for different core versions, please also see this issue: http://drupal.org/node/107721

karldied’s picture

karldied commented
Status: Needs work » Fixed

The documentation writer's guide is posted at http://drupal.org/node/336. Thanks for the good feedback and comments.

Summary of related issues:
http://drupal.org/node/105356 - Make documentation specific to drupal version (open)
http://drupal.org/node/107721 - Allow documentation maintainers to more easily copy nodes (open)
http://drupal.org/node/107953 - Authoring Guidelines for placing/ organising v4.x and v5 documentation (fixed)
http://drupal.org/node/110062 - Update to Documentation writer's guide (fixed)

The new Documentation writer's guide is issued under #4.

#3, this issue, was treated as a sub-section of #4. Note that existing guidance was 'Option 1' of those listed on Jan 9 above, and is the one proposed above, and in the current doc writer's guide. #1 requests 'Option 3' of those listed on Jan 9.

For #3, I also updated http://drupal.org/node/14279 - About Drupal documentation, to discuss that handbook pages are marked for version applicability.

Anonymous’s picture

(not verified) commented
Status: Fixed » Closed (fixed)