The discussion at #2956879: Proposal: Create and promote new "Quick-start guide" pages → has brought up many ideas and pain points about the many silos of documentation that exist to help Drupal users, developers, and evaluators. As has been pointed out by many, the purpose, audience, organization, ownership, and maintenance of these various documentation efforts isn't always clear or straightforward, and this confusion can unfortunately sour the experience of Drupal users, developers, and evaluators.
It was suggested in #2956879 that a "meta" issue be opened to analyze these various "big picture" Drupal documentation problems at a holistic level, link to issues that seek to address these problems, and do so here in this meta issue, instead of in individual issues that seek to keep their scope in check and tackle a discrete issue.
Some of the problems/tasks that have already been identified are:
1. Identify all of the "silos" of Drupal's documentation and answer the following questions about them:
- What is the silo called? (i.e. Drupal 8 User Guide, Community Documentation, etc.)
- What is the URL of the primary landing page(s) for it?
- Who owns it?
- Does it have active maintainers?
- Who can contribute to its content?
- Is there a documented process for contribution to it?
- What best practices does it employ?
- What are some pain points with it?
- Why does it exist? (What is its purpose?)
- Who is it for? (Who is its audience?)
==> A list of the documentation "silos" is being collected at https://docs.google.com/spreadsheets/d/1IM1a6WDS9x8WJRX3VLvGLlIa93hbsgQ-... -- anyone wanting edit access, contact jhodgdon → in Slack or using her drupal.org contact form, and provide the email address you use for Google.
2. What are ideas for improving Drupal's documentation, at a big picture level. This could related to any or all of:
- Organization, structure, and navigation
- Ownership, maintenance, and contribution
- A vision for the future
- Policies and procedures
- Clarifying the purpose visually, through organization/navigation, or other means
- Directing users to the appropriate silo of documentation or promoting certain silos
3. Current issues
- What issues are currently tackling some of these problems? Let's link to them in the "Related Issues" section of the issue, in an effort to see what's happening at a big picture level.
4. Pain points
a. The Drupal Association (DA) owns drupal.org and some of its content. Community members wanting to make changes to the structure of drupal.org, and to DA-owned content, need to get agreement from the DA staff before it will be possible.
b. The dividing line between Documentation (content that the community owns on drupal.org) and Marketing (content that the DA owns on drupal.org) is not necessarily clear.
c. For some reason, the Community section of drupal.org has been defined in the past as owned by the DA and not by the community.
d. Various pieces/silos of documentation are generated from different sources using different technology
e. There is a documented process (the
"Documentation Gate" →
) that says that changes in Core code are supposed to be matched with changes in documentation. Three pain points with that:
- It doesn't always happen completely.
- Contrib modules don't necessarily hold themselves to that standard.
- There is nothing in the Documentation Gate that says that documentation pages on drupal.org get updated -- it's all about what has to get into the patch to the Core code and its in-code and in-Drupal documentation.
As we identify pain points and ways to address them, let's work on a list of possible goals that could emerge from this issue.
- Create an inventory of documentation pain points aka the many documentation silos (in progress)
- Introduce transparency into who owns, is responsible for, can maintain, or who can edit any documentation page on Drupal.org. Possibly create a responsibility assignment matrix (this could emerge from the documentation pain points inventory currently underway) to define and clarify key responsibility roles for documentation or documentation-like pages (i.e. resource guides or other "informative marketing pages").
- Create new issues to address documentation pain points
- Prioritize issues that address documentation pain points and possibly create a tag to identify these priorities
- Coordinate contribution efforts to move prioritized issues forward to completion
This is just an initial stab at a meta issue. Suggestions welcome for improving it.
Active
Other documentation issues
Not all content is available!
It's likely this issue predates Contrib.social: some issue and comment data are missing.
I was commenting on 🌱 [policy, no patch] Add link to change record in code comments Active and wanted to know what was in the spreadsheet about change records. However, the spreadsheet referred to in this issue, in the issue summary has been deleted.