Problem/Motivation
Currently we have a complete mix:

  • some pages talk about multiple versions at once
  • some pages don't talk about specific version at all
  • some guides have separate pages per version

Users need to very clearly understand what version the page is talking about. Mostly they need to see content about only one version of Drupal on a single page (unless it is content about migrations). We need a consistent way to deal with versions.

Plan

Major versions - D6 vs D7 vs D8

Documentation split per major version example

  • All documentation split at the top level
  • Each guide* (ideally) has 'Changes from Drupal n-1' page, which will specifically describe the differences and link to relevant change records. We will recommend and encourage this behavior.
  • Each guide* (and all pages inside of it) have one clear major version.
  • Documentation for non-supported versions (e.g. D6 after Feb 24) clearly marked as such.
  • Guides* per version can have completely different steps or sub-sections inside.
  • This will make it easier to see all documentation for a specific version and identify gaps.

Minor versions - 8.1 vs 8.2

  • Will be managed within documentation for appropriate major version
  • Differences between minor versions will be explained using pre-defined templates (CKEditor templates) within content. E.g.:
    example wireframe for documentation call outs

Connections between same documentation for different major versions

We are looking at a couple of approaches

Approach 1:

  • Using an optional 'Related content' field available on both Guides and Documentation pages
  • This is a simple approach, having one optional field is more flexible and can be used for 'this documentation in another versions' only when it is needed.
  • We'll need to make sure that version is clearly displayed on each related item. With some of them potentially being non Documentation content types and thus having no version.
  • This might be less obvious to users as the link will be 'lost' amongst other related content. With the whole field being secondary information for the primary content and thus displayed not too prominently.

Approach 2:

  • Use an entity reference field to add 'This documentation in another version', with the ability to specify version.

    This page for:
    Drupal 8 [ ]
    Drupal 7 [ ]
    Drupal 6 [ ]

  • This would be separate from 'Related content' field, making it a little more obvious for users.
  • Would let us display 'per version' links separately from Related content, in a recognizable place.
  • We could do things like - display a call to action 'Rewrite this documentation to Drupal 8' when D8 version does not exist. However this might not be applicable for all documentation. We would need to provide 'n/a' option or similar to hide the CTA in such case.
  • This would add more fields to the edit form.

Remaining tasks

This will be implemented as a part of overall migration of the Documentation into a new Section #2533684: Create 'Documentation' Section.

*When using 'guide' in the context of this issue we mean the new group content type called 'guide' described at #2679635: Create group content type (guide) for documentation, not the top level books such as 'Site Building Guide'.

CommentFileSizeAuthor
#7 call-outs-wireframe.png26 KBtvn
#7 major-version-split.png41.44 KBtvn
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

babipanghang created an issue. See original summary.

babipanghang’s picture

droplet’s picture

Priority: Normal » Major

Totally true. We should not make the Doc to be a history book.

For example,

when you installed fresh new D8 and report page's error message suggested you to this page: https://www.drupal.org/node/1992030

what you wanna know is "Trusted host security setting in Drupal 8" section only.

Aanal.addweb’s picture

Issue summary: View changes
tvn’s picture

Title: Split up documentation » Split up or better display documentation per Drupal version
Issue tags: +drupal.org documentation
Parent issue: » #2533684: Create 'Documentation' Section

We'll be looking at some of the options on how to do this as a part of work on Documentation section and improved content types for docs.

tvn’s picture

Title: Split up or better display documentation per Drupal version » Split documentation per Drupal version
Assigned: Unassigned » tvn
Issue summary: View changes

Updating issue summary with our current plan on how to tackle this.

tvn’s picture

Issue summary: View changes
FileSize
41.44 KB
26 KB

Adding images.

tvn’s picture

Issue summary: View changes
tvn’s picture

Status: Active » Fixed

Marking this fixed as we are proceeding with the plan outlined in the issue summary. The actual split will happen during the migration #2762837: Migrate documentation into the new system.

Status: Fixed » Closed (fixed)

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