>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3441158. --> Reported by: [bradjones1](https://www.drupal.org/user/405824) >>> <p>Drupal is an amazing CMS/framework appropriate for building a wide range of ambitious, technically complex, interactive web applications.</p> <h2>Problem statement/motivation</h2> <p>Despite clear competitive advantages in the realms of technology, community, flexibility and more, the project suffers from significant marketing and DX debt of a ~20 year old project. This is particularly true in the realm of the official documentation.</p> <p>At the outset, I want to state clearly that none of the opinions shared on this meta issue, and the proposals made, are not intended to diminish the many thousands of hours of contributed time spent on the docs to date. Rather, the tools we currently use to share our technical story are outdated and there are better options available to us. Contributors to Drupal's documentation deserve a better stage on which to shine.</p> <p>There are initiatives underway to improve Drupal's position in the competitive landscape through outreach and marketing, however to my knowledge documentation is not officially part of these plans. I believe we can make a modest and realistic investment of time and effort resulting in a sea-change improvement in Drupal's documentation. A project with clear, accessible, up-to-date documentation is more appealing to developers and by extension, their employers who choose to use Drupal over many alternatives.</p> <p>We fall short as a project on two main fronts: Outward-facing/end-user documentation experience, and contributor experience.</p> <h4>End-user documentation experience</h4> <p>A user searching for "Drupal documentation" on Google finds the first four results pointing at entirely different landing pages on Drupal.org: "<a href="https://www.drupal.org/documentation">Documentation</a>," "<a href="https://www.drupal.org/docs">Drupal Wiki</a>" (at <code>/docs</code>), "<a href="https://www.drupal.org/docs/develop">Develop</a>," and "<a href="https://www.drupal.org/docs/user_guide/en/index.html">Drupal User Guide</a>." These related, but rather distinct, entry points into Drupal present a disjointed experience. In addition, there are many cases where documentation refers to specific versions of Drupal, particularly Drupal 7. As D7 and D8+ are basically different software experiences, this adds to the confusion.</p> <p>The quality of documentation on Drupal.org varies from detailed and technical to wrong and/or outdated, or not reflecting "best practice." Due to challenges in the contribution experience (see below) it is sometimes unclear that documentation can be updated, or user guide ownership means permissions are a hurdle to improving or correcting docs.</p> <p>The limitations of the official docs have led some in the community to go their own way. A significant body of Drupal documentation exists in blog posts (e.g., on agency sites) and even comprehensive alternative docs like Selwyn Polit's <a href="https://selwynpolit.github.io/d9book/">Drupal Book</a>. There will always be "docs in the wild" for any software, however my personal experience is that these docs are often superior or more trustworthy than the official documentation on drupal.org.</p> <p>If you are an evaluator, Drupal's official documentation does not instill trust when compared to docs for <a href="https://symfony.com/doc/current/index.html">Symfony</a> or <a href="https://laravel.com/docs/11.x/readme">Laravel</a>. Interestingly, the official <a href="https://wordpress.org/documentation/">WordPress</a> docs are a bit neater but (IMO) very sparse and unhelpful.</p> <p>Drupal's documentation is also not exclusively limited to the "official" docs. An important source of truth and updates to the software are contained in <a href="https://www.drupal.org/list-changes/drupal/published">change records</a>. Core has a strong quality gate for CRs, however many users will find them difficult to discover via the documentation system and they are primarily linked to resolved issues. In fact, <a href="https://www.drupal.org/project/drupal/releases/10.2.5">releases of core</a> link to commit messages only, and not change records, meaning end users do not have a "direct" path to viewing all change records applicable to a release (despite this information existing in the drupal.org database, at least by way of a freetext field.)</p> <h4>Contributor experience</h4> <p>Community contribution is at the heart of Drupal's success. We enjoy a real "first-mover advantage" in our community structure, especially our issue credit and organizational recognition system which has helped to incentivize and recognize open-source contributors.</p> <p>Notably, contributions to documentation are severely under-counted in the <a href="https://www.drupal.org/drupalorg/contribution-credit">contribution credit system</a>. In fact, it's not counted at all! Drupal.org user profiles do say "Over 5 edits to documentation," but that's both vague and unrelated to your issue credit "score," if that's important to you/your organization.</p> <p>Drupal.org's documentation system is centered around the wiki, which is editable by registered users and does boast a "discuss" functionality similar to Wikipedia. While the wiki model works well for many knowledge bases, very few users contribute to the docs in this manner and there is no staging or change-proposal system in place.</p> <p>Finally, and by way of segue into proposed solutions, documentation is decoupled from code. This means that updated documentation cannot be reliably enforced as a quality gate for core commits.</p> <h2>Proposed solutions</h2> <p>I propose that the official Drupal documentation move into the codebase, with documentation coexisting with code. With the move to GitLab CI, we have the ability to add custom jobs to the Drupal Core CI configuration, which could include generating a static site for all supported versions of the project. This site would be a CI artifact and would immediately update a docs site, e.g. at <a href="https://docs.drupal.org">https://docs.drupal.org</a>.</p> <p>Now is the time for action on improving Drupal's documentation, both for end-users and contributors. Drupal.org is on D7 and much of its functionality is being pared down as a result of the GitLab migration. As the DA must plan the future of the D7 install, the docs system must be accounted for and migrated "somewhere."</p> <p>Just like drupal.org's homegrown issue tracking system was created because it literally predates GitHub, GitLab and similar, the docs wiki has been eclipsed by more modern alternatives.</p> <p>Benefits of such a move are significant. Contributors of documentation would get contribution credit for their work with no change to the underlying technology stack for assigning credit. The drupal.org technical footprint can shift docs away from the CMS and into the realm of cheap, repeatable CI jobs. Hosting costs are (potentially) reduced as a static site can be hosted on cheap object storage behind CDNs (cache invalidation considerations notwithstanding.) The docs can be more modern in style and functionality, since we can offload the technical foundation to open-source software like Docusaurus. And the docs generation system can even hook into things like automated docs generation from code (e.g. for API docs) as well as linting the documentation for dead external links.</p> <p>A growing number of projects in the drupal.org ecosystem are already publishing their documentation with GitLab pages. We could wire up code to identify which projects have a pages integration and automatically link to them. External resources can be linked as well, creating a more interconnected web of docs, official and otherwise.</p> <p>Non-technical or less-technical editors of documentation can take advantage of the web IDE in GitLab for proposing docs changes, and we can move to Markdown for formatting which is easy and increasingly familiar to end users (if Redditors can do it, so can we!)</p> <p>Perhaps most importantly, core contribution can make docs updates and additions a mandatory quality gate for code contribution. If you create a new API or feature, it must be documented (if even just in Doxygen which is then parsed into something pretty). We could even convert change records to be in the codebase, and they would be packaged up at release time. (See <a href="https://github.com/expo/expo/blob/main/CONTRIBUTING.md#-updating-documentation">Expo</a> for an example of this.)</p> <p>We have the tools, and even a large amount of existing documentation to seed the new-and-improved docs. Through at least July, my core contribution time is sponsored by the kind folks at Optasy, so I can commit to helping lead an initiative. While this is a "big" change for Drupal, I honestly don't think it's that "hard." The main challenge will be getting agreement on a project plan and coordinating with relevant stakeholders (core committers, the DA/drupal.org maintainers, existing docs owners) to build consensus. This community is full of people with a bias for action, and I'm optimistic that this could help with selling Drupal as a modern framework/CMS that is anything but old and crusty.</p> <h2>Remaining tasks</h2> Issue summary update > Related issue: [Issue #3176075](https://www.drupal.org/node/3176075)