Contrib.social

Unify/normalize module documentation systems

Open on Drupal.org →
Created on 15 February 2023, over 1 year ago

Problem/Motivation

As of now, Drupal module developers have the following (and upcoming) systems to create and maintain module documentation and help (see help and documentation for a discussion on whether they are related concepts)

This poses the following challenges:

  • Multiple sources of information are difficult to keep in sync. It's not difficult to find outdated module info. This is especially true for drupal.org documentation: it's not strange to see that the README.md is more reliable as a documentation source than the online documentation or the project description
  • Lack of developer consensus about how to use them: some developers use hook_help just for a brief snippet of info and README.md for full details, others prefer to output the docs to the admin UI and keep a brief README.md and others just put all the info into drupal.org and reference it from the module via links.
  • Maintainability: for each change, a developer should need to update up to six sources of information

This not only affects developers but Drupal as a whole: having outdated, sparse or decentralized sources of information might affect Drupal adoption as newcomers are often confused.

The developer need for less sources of documentation/help has been evidentiated by issues such as [PP-3] Allow README.md to optionally render a project page ✨ Allow README.md to optionally render as the project page Fixed

Proposed resolution

Ideally, modules could implement a single source for documentation that might be consumed from elsewhere (help system, drupal.org, etc) and this should live within the source code.

This way:

  • The developer would need just one update for their change to spread elsewhere.
  • The documentation could be read directly from the repo or from documentation UIs (akin to what developers can do with Drupal APIs)
  • The documentation would be version-controled, reversible, tied to specific versions of the module
  • Less overweight would be put into maintaining and developing the drupal.org documentation and it would be much more complete and updated. This could ease Drupal adoption and make it competitive with better documented tools.

This is not different on how Drupal API works, and it's very common on other frameworks and tools where documentation lives in the source code and is parsed / fetched in order to generate a documentation UI (think mkdocs, for example).

This could be implemented on different ways:

  • As .md files on a /docs or similar folder (plus README.md as the entry point)
  • As twig templates with frontmatter, as proposed by the experimental Help Topics → module
  • Other options to discuss...

Drupal.org integration

This should be part of a different discussion on drupal.org issue queue in case this got to be implemented.

Some quick ideas:

  • Drupal.org could parse the readme.md file and populate the description with its contents. We could have tabs for the different branches of the module.
  • Then, it could parse the /docs folder to generate documentation pages.
  • On drupal.org documentation could be read "as-is" from the module or could be fetched and then editable, similar to this proposal on [PP-3] Allow README.md to optionally render a project page ✨ Allow README.md to optionally render as the project page Fixed . We might not want to lose the ability to extend the docs on drupal.org, but we would benefit from having at the very least an auto-generated and up-to-date documentation page for each module.

Help and documentation: are they the same?

Help topics and documentation can be considered aspects of the same (help being part of the docs, think FAQs) or completely different systems:

  • Documentation is usually aimed to developers, is thorough and is structured
  • Help is aimed to end users or site builders, takes the form of small sets of instructions and is much better if it's brief and contextual (see Help Topics → or Tour → )

If we consider Help and Documentation to be completely separated, we could completely exclude the help ecosystem from this issue (hook_help, Help Topics).

On the other hand, Help could be part of the documentation written on the source code (think FAQs: they are small, brief, contextual) and they could be referenced from modules such as Help Topics.

I.E the developer could maintain structured Help topics / FAQs on the documentation and then reference them individually via a module in order to insert them (as Blocks, etc) wherever needed, providing an UI for the user while keeping a single source of info.

Remaining tasks

Discuss, gather consensus, implement.

User interface changes

None: help topics, etc... should remain the same, just the source changes.

API changes

To be discussed.

Data model changes

None

✨ Feature request
Status

Active

Version

10.1 ✨

Component
Extension  →

Last updated 3 days ago

No maintainer
Created by

🇪🇸Spain idiaz.roncero Madrid

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

contrib.social Blog FAQ Discussions
Production build 0.69.0 2024