As a part of an overall overhaul of documentation on Drupal.org (#2533684: Create 'Documentation' Section), we want to connect documentation to projects, to enable 'official' project-specific documentation.

*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'.

Plan

  • We will create top level guide for Contributed projects documentation per major version
  • Documentation for specific project or a group of related projects will be created as guides inside of it
  • We might need additional structure inside of 'Contributed projects' guide at some point, but we can figure that out as we go.
  • contrib projects documentation guide location

  • Project maintainers on their project pages will have a 'Project documentation' entity reference field. Where they will be able to add multiple guides and specify project versions each specific guide is applicable for.
    project documentation field image
  • Applicable versions should match project branches
  • 'From' version is required, 'To' is optional. If 'to' is blank, means the documentation is only applicable for the one specific version (in 'from' field).
  • If the documentation is applicable for *all* after specific starting one, users should enter 8.1+ in the 'from' field. We'll add help text to clarify this.
  • Related projects and their version will then be displayed on documentation guides and pages.
    related projects display
  • On project pages we will display Related documentation guides and versions they are applicable for.
  • We could potentially add a view of all Documentation guides for specific project.
Members fund testing for the Drupal project. Drupal Association Learn more

Comments

tvn created an issue. See original summary.

tvn’s picture

tvn’s picture

Issue summary: View changes
tvn’s picture

Assigned: Unassigned » tvn
Issue tags: +d.o documentation
Parent issue: » #2533684: Create 'Documentation' Section
drumm’s picture

Would it work to rely on the related content fields on documentation pages & guides? Listing guides and/or pages related to a project on the project page.

This doesn't give us the version number selection. That would of course simplify implementation quite a bit.

It does move control of documentation for a project firmly to the people taking the initiative to write the documentation. I think that might be good, project maintainers are often not the ones doing the documentation. It does get more immediate exposure to potentially mediocre documentation, the project maintainer isn't a gatekeeper; when that happens, the project maintainer updating the documentation, removing the link if necessary, can be encouraged.

tvn’s picture

I do not think it would work, for a number of different reasons:

  • The idea and design for that field was to make 'official' documentation for a project possible and display it prominently.
  • Project can be 'related' to many different documentation pages, e.g. the ones that describe relevant concepts in Drupal or list different ways of solving the same task, but those pages are not necessarily 'documentation for this project' and thus should not show up on the project page.
  • We do need a way to define which version documentation guide applies to, contrib especially can be very different between minor branches.
  • Related content field is open to everyone, thus project maintainers will have no control over what is shown on their project page.
drumm’s picture

Ok, then we’ll want to do a multi-valued field collection containing the single-valued entity reference, and 2 text fields for the versions. (There’s a way to convert those to version number select lists, like we have on issues. Will be done for #2461167: Create Security announcement content type.)

tvn’s picture

Issue summary: View changes

Clarification.

drumm credited B_man.

drumm’s picture

Status: Active » Needs review

  • drumm committed a7de6b0 on 7.x-3.x, dev
    Issue #2679643 by B_man: Connect projects to documentation guides,...

  • drumm committed 20e6d0f on 7.x-3.x, dev
    Issue #2679643: Use contrib-style version numbers
    
  • drumm committed 91d77f0 on 7.x-3.x, dev
    Issue #2679643 by B_man: Do not add documentation to translation...
drumm’s picture

Status: Needs review » Fixed

This is finishing up deployment now, the fields are in place and the display on guides is coming up.

Status: Fixed » Closed (fixed)

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