>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #2956879. --> Reported by: [webchick](https://www.drupal.org/user/24967) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>Myself, along with some of my co-workers, were tasked by Dries to perform a series of interviews along with other research to try and determine what the main blockers are for Drupal 8 adoption, as well as what factors are leading to Drupal 8 being hard to use. (These findings will be part of the Driesnote at Nashville.)</p> <p>We've talked to over 50 people at this point, from site builders, to developers, to support and sales people, to trainers, both enterprise-level and small-medium business level, from various points on the globe including North America, Europe, and India. From this research, we feel we've gleaned a solid set of common pain points and have some suggested next steps.</p> <p>One of the common complaints&mdash;surprise, surprise&mdash;was around Drupal's documentation. But specifically, about the inability for people to find curated, <em>opinionated</em> documentation that recommends a single "best practice" way of doing various "getting started" things: setting up a local dev environment, installing, using Composer, managing configuration, etc.</p> <p>Now, we <em>do</em> have curated documentation, in the form of the <a href="https://www.drupal.org/docs/user_guide/en/index.html">Drupal User Guide</a>, but it's still difficult to find (the Google juice with the wiki docs is still strong...), and even that resource goes out of its way to be more comprehensive and expansive vs. opinionated and brief. (For example, compare <a href="https://www.drupal.org/docs/user_guide/en/installation-chapter.html">https://www.drupal.org/docs/user_guide/en/installation-chapter.html</a>, which covers a full gamut of available web server options, external tools options, etc. vs. <a href="http://symfony.com/doc/current/setup.html">http://symfony.com/doc/current/setup.html</a> which is about one page and BAM, you're in.)</p> <p>See <a href="http://matthewgrasmick.com/compare-php-frameworks">http://matthewgrasmick.com/compare-php-frameworks</a> for a comprehensive look at the problem the lack of this information creates for evaluators.</p> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>Improve the Drupal evaluator, developer, and site builder experiences through improved documentation on Drupal.org. This initiative will increase the visibility and accessibility of the existing curated documentation on Drupal.org and also introduce a new class of "one-pager" guides that are opinionated about a single, recommended way to accomplish common tasks.</p> <p>The goal is <em>not</em> to replace or supersede the existing Drupal User Guide (which is an excellent, comprehensive resource), but rather to better promote it on various places in Drupal.org's information architecture, and supplement it with targeted, focused guides that follow a well-defined set of standards and maintenance practices pioneered by the Drupal User Guide.</p> <ul> <li>Introduce and announce a new "class" of Documentation on Drupal.org: "Promoted Drupal Docs&rdquo; (or some similar synonym) <ul> <li>Include the Drupal 8 User Guide in this class</li> </ul> </li> <li>Add new, opinionated "one-pager" guides that provide a single, recommended way to accomplish common tasks: <ul> <li>Evaluator Guide</li> <li>Getting Started Guide</li> <li>Configuration Management Guide</li> <li>Composer Guide</li> </ul> </li> <li>Adopt best practices established by the Drupal 8 User Guide: <ul> <li>Documentation will be version controlled.</li> <li>There will be multiple versions of each guide, corresponding with Drupal core minor and major versions. E.g., 8.5.x, 8.6.x, 9.0.x, etc.</li> <li>Documentation maintainers will coordinate with core committers to ensure accuracy and coverage. </li> <li>A documentation governance process will be put in place, requiring that all documentation is reviewed and meets the defined set of standards.</li> <li>The community will be able to contribute to documentation within the confines of the established processes. </li> </ul> </li> <li>Make UX changes on Drupal.org: <ul> <li>Prominently link to &ldquo;Promoted Drupal docs&rdquo; in major Drupal.org entry points.</li> <li>Minimize the importance and visibility of "wiki-style" documentation.</li> <li>Clearly label and organize documentation according to Drupal version. E.g., 8.5.x, 8.6.x, 9.0.x, etc.</li> <li>Use left-hand sidebar to display documentation hierarchy.</li> </ul> </li> </ul> <p>See also <a href="http://matthewgrasmick.com/posts/documentation-initiative-proposal">http://matthewgrasmick.com/posts/documentation-initiative-proposal</a> for a longer-form version of this proposal.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li><del>Initial idea vetting with community members involved in documentation</del></li> <li><del>Initial idea vetting with Drupal Association staff</del></li> <li><del>Open issue in ideas queue for public discussion period</del></li> <li><del>Identify maintainer(s) for the various new guides, with committed time to not only initially author, but also maintain on an ongoing basis, including incorporating community suggestions.</del></li> <li><del>Identify initiative coordinator(s) - <a href="https://www.drupal.org/u/grasmash">@grasmash</a> has offered to help lead this initiative.</del></li> <li><del>Get product management sign-off on idea</del></li> <li><del>(After that) Develop more detailed implementation plans, including biksehedding the particulars about each guide (in other words, please don't delve into "tool A vs. tool B" details here... ;))</del></li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <ul> <li>New documentation guides</li> <li>Information Architecture changes on Drupal.org*</li> <li>Changes to Drupal.org landing pages*</li> </ul> <p>* These items are owned by the Drupal Association. The DA has offered their commitment here, provided that they are closely involved in requirements gathering for any changes that might be needed.</p> <h3 id="summary-api-changes">API changes</h3> <p>N/A</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>N/A</p> > Related issue: [Issue #2828874](https://www.drupal.org/node/2828874) > Related issue: [Issue #2857775](https://www.drupal.org/node/2857775) > Related issue: [Issue #2969725](https://www.drupal.org/node/2969725) > Related issue: [Issue #2977535](https://www.drupal.org/node/2977535)