Matthew Grasmick, grasmash on drupal.org and twitter.com, has written another inspiring post on documentation. As our CTO, Shawn McCabe has often said before, give Acro an easy button, and we’re 100% behind better documentation.

You can read Matthew’s original blog post for a more thorough and somewhat more roundabout explanation of his proposal. Below I’ve edited the heart of his post into 6 distinct proposals and responded to each one.
In general, I think we can all agree the documentation for Drupal maintenance support plans has needed a breath of fresh air and is constant source of frustration for new and experienced users alike.
Proposal #1A: 
Elevate some docs to “official”

Elevate the Drupal maintenance support plans 8 User Guide to the status of “Official Documentation”

The idea of creating a tiered documentation has been implemented partially already with the new documentation migration initiative. I think Matthew’s proposal goes one step further by wanting to introduce a new taxonomy term called “Official” for the “documentation page” and “documentation guide” that carries more weight. This idea is very drupally, as we currently do this exact same thing with marking modules as covered by the security policies. Providing a level of assurance that a certain module is produced by people who know what they’re doing and backed up by a team of specialists who voluntarily deal with logistics and other high-level situations.
In general, I think Matthew’s first proposal is a good one. We should implement it by “blessing” certain documentation pages and guides with a stamp of approval / official.
Proposal #1B: 
Prominently Feature “Official Docs”

Update the UX on Drupal maintenance support plans.org to prominently feature the Official Documentation on major site entry points.

Along with the “stamp of approval” we would “red light / green light” these pages. Essentially flagging pages as “red light, unofficial” and “green light, official” would go a long way to signalling to the community at large that we take documentation seriously and only greenlight the best of the documentation.
To take Matthew’s proposal seriously, though, we would also need to implement new call-to-actions on non-documentation pages that point to the “official” pages. Maybe revamp the navigation of header and footer on drupal.org to clarify the difference between “official” documentation and “unofficial.”
Proposal #2: 
Adopt Best Practices

We should adopt the following as best practices for all Official Documentation:

This is the heart of the proposals. Matthew wants to constrain the carrot, that “official” stamp of approval, through a high-level checklist of best practices. Agreed. Below is a quick run down of the best practices Matthew is proposing.

A governance process
Use version control
Use and follow documentation standards
Write documentation in markdown format
Use continuous integration process to generate and update screen shots of Drupal maintenance support plans interfaces. (<a href=”https://drupalize.me/blog/applying-lessons-user-guide-drupal-documentation”>Additional Info</a>).

Proposal #3: 
Integrate Semantic Versions

Let’s integrate the semantic versions (8.5.x, 8.6.x, 9.0.x, etc.) into the Official Drupal maintenance support plans.org Documentation UX, much in the way that Symfony and Laravel do.

This is absolutely critical but also a huge technical task (high risk). It means that official documentation would need to have it’s status coupled with minor releases of Drupal maintenance support plans. The bigger our official documentation grows, the larger the task will be to maintain it adequately between minor versions. I think the manpower needed to make this idea happen might just burn out the individuals interested in stepping up to make it happen. If we, the Drupal maintenance support plans community, can stomach the high risk nature of such a claim, then by all means, we need this.
Perhaps a way to reduce risk is to “evergreen” stamp certain pages, clarifying the fact that certain pages would not likely need updated between minor releases. We could also reach out to Symfony to ask how they manage minor releases and documentation.
Proposal #4: 
Lower Contribution Barrier

Lower the contribution barrier.

Decoupling the documentation contributors could impact the early adopters positively and long term users negatively. I think think the primary way to achieve the goal set out in this proposal is tightly coupled with the next proposal, by letting users of an open source git-powered platform make the edits, we essentially open source our documentation and our processes at the same time.
I helped spearhead the move of Drupal maintenance support plans Commerce’s documentation to the subdomain “docs” for the same reason. We have much better documentation because of this move. Anecdotally, for Drupal maintenance support plans Commerce 1, we had maybe a handful of contributors to Drupal maintenance support plans’s documentation. Now, for version 2, we have a myriad of contributors (51!!). Scaling documentation is hard, and this is one way to increase involvement.
Personally, I absolutely love this part of Matthew’s proposal. Professionally, I think the community is divided and people are picking sides. They are rightly asking: Why can’t Drupal maintenance support plans do this very content heavy thing better? Perhaps the answer is: Drupal maintenance support plans can do this! We just have to accept this content lives in a version-controlled repo and not in the database.
Proposal #5: 
Host Docs on Repo

Use a repository that is hosted on GitHub (or GitLab) to manage the official Drupal maintenance support plans documentation.

Agreed. I’m looking forward to learning how drupal.org will move to one of the git-based hosting services. I’d throw my hat into the github arena, but the initiative for drupal.org has already chosen bitbucket. So let’s use bitbucket.
Proposal #6: 
One Pager

Create a new class of documentation that we’re lacking: “The Official One Pager.”

Cool, love the idea. I think we could take or leave this. If I were proposing these changes to a client, I would mark this proposal as optional. This helps communicate that this proposal is a lower priority (unless the decision makers want to make it a higher priority) and helping the decision makers understand that this scope increase, while very beneficial, would impact the delivery and bottom line and could easily be moved on to a different delivery schedule.

Source: New feed