How can we fix Drupal’s documentation?

Phase I: Standards & Governance

  • Official, published Drupal documentation should not be editable by any random person with a drupal.org account.
  • There should be a new, official role in Drupal’s governance model: that of Documentation Maintainer. These people would have similar power and stature as committers currently do, and they would be mentioned in MAINTAINERS.txt. However, their job would be to review and publish changes to Drupal’s official documentation, rather than control changes to the code base. Ideally, they’d be a mixture of experienced site builders and developers, so that the documentation can properly address Drupal’s mixed audience.
  • Commits to core should be blocked on documentation. If you are going to add a feature to core, you should have documentation for that feature which will go live as soon as your patch lands. Documentation maintainers would have the power to block commits until the appropriate documentation was written up to the agreed-upon standards. In other words…treat documentation exactly how we currently treat patches.
  • Unpublished, in-progress documentation could be worked on by anyone. Once a documentation change goes live, everyone who worked on that set of changes would receive an honest-to-Gawd commit credit for it. Documentation is hard, crucial work and should be recognized accordingly. As a legendary core developer once told me, credit where credit is due is the foundation of open source, and there are many contributors who could do invaluable, top-notch work in the documentation space if it wasn’t thankless, second-tier drudgery.
  • Where appropriate, documentation should use images and video to illustrate concepts. Documentation maintainers should be able to kick proposed changes back for lacking enough audiovisual material.
  • Documentation should have plenty of examples.
  • Proposed documentation changes should always be vetted and tested by subsystem maintainers to ensure technical and practical accuracy. It should also be vetted by documentation maintainers to ensure that it is well-written, well-organized, concise, and properly proofread.
  • It should be real easy to format documentation in a consistent manner. To me, that means Markdown support. Making authors mark everything up in pure HTML is asking for trouble, and will slow down any effort to get good documentation written.

Phase II: Overhaul & Migrate

Phase III: Implementation

In closing…

--

--

--

Dispatches from the dimension of demented Drupalists. Also, assorted bullshit.

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Linux boot sequence

Linux boot sequence

Risks and Rewards of Hiring A Full Stack Development Company

Full Stack Development Company

Terraform tips for newcomers

AMA With Im Community

Advantages And Disadvantages Of Python For Your Business

custom apps development services

Amazon Elastic Kubernetes Service(EKS) Setup

Advantages of Using Fish Shell 🐟

[LeetCode]#561. Array Partition I

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Phéna Proxima

Phéna Proxima

Dispatches from the dimension of demented Drupalists. Also, assorted bullshit.

More from Medium

Introducing @mockapi/msw, mock an API server for your entities without writing any code with Mock…

Setting up Tailwind 3 in Electron-React-Boilerplate (Updated Jun 2022

WWDC 2022 Key Hardware Updates

Okta vs. Other Authentication/Authorization managers