[Meta] Completely rethink documentation requirements

Created on 3 June 2025, 3 days ago

Problem/Motivation

I believe we can consider the current "everything must be documented" an utter failure which needs to be thrown away and the requirements completely rethought. It won't be objective, that was tried and failed. Time to do something better.

In specifics, FieldTypeCategoryInterface for example has a single line documentation which just reshuffles the words already in the name of the interface: "Provides an object that returns the category info about the field type" which tell us absolutely nothing meanwhile FieldTypeCategoryInterface::getWeight has six lines of documentation which tells us in very great detail how this method returns the weight of whatever this object represents. The correct balance would be about six lines on FieldTypeCategoryInterface and zero on getWeight. For the six lines, invoke Kipling's six: What and Why and When And How and Where and Who. OK maybe skip the who but the rest are valid questions to expect answers to.

Of course, FieldTypeCategoryInterface is not at all alone in this. RouteProviderInterface "Defines the route provider interface." Or look at MenuLinkInterface "Defines an interface for classes providing a type of menu link." MenuLinkInterface::getWeight? six lines. ::getTitle? Six lines but the summary is useful. ::getDescription? this six lines is worse than useless, this is a bug because getTitle says it returns a localized title but description is mum on localization. Which shows clearly when you need documentation: when it's needful. And no, neither getTitle nor getDescription needs the same information twice, once in summary once in return.

Steps to reproduce

Proposed resolution

Throw away the current rules and write new ones where the documentation is focused on helping developers instead of passing phpcs.

Remaining tasks

Everything.

User interface changes

Nothing.

Introduced terminology

Hopefully a great many things get explained even if not introduced.

API changes

Data model changes

Release notes snippet

๐ŸŒฑ Plan
Status

Active

Version

11.0 ๐Ÿ”ฅ

Component

documentation

Created by

๐Ÿ‡จ๐Ÿ‡ฆCanada Charlie ChX Negyesi ๐ŸCanada

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

Comments & Activities

Production build 0.71.5 2024