[meta] Identify and Address Documentation Pain Points

Excellent, thanks Amber!

There was an effort a couple of years back to do a full Drupal.org content audit funded by the Drupal Association, which can be found over at #2574783: Content Audit for documentation on Drupal.org. That might be useful as a starting point for highlighting the various silos.

It sounds like another good thing coming out of this a proposed RASCI matrix of who should be responsible for what, consulted on what, etc. I know that's been a huge source of consternation in the past when the Documentation Team, the Documentation Working Group, and the Drupal Association aren't aligned with one another.

Adding some related issues. There are a bunch...

Editing issue summary. I think we should just use the Related Issues section to list related issues, unless we want to annotate each one?

One more related issue.

Is there someone who could build a view list of content on drupal.org where it is.. Not a module or theme node and is Published ?
Without systematically going through all the pages I don't see how we're going to discover everything and be able to build that roadmap to 100% accuracy

And,

2. What are ideas for improving Drupal's documentation, at a big picture level.

That has to be this one
Ensure all Drupal.org stakeholders understand the need for a coherent, consistent strategy of content in general for Drupal.org to prevent fractured documentation and other content on drupal.org
- it does not get more 'big picture' in my opinion than organisational change.

This seems to be re-occuring theme due to the lack of (I believe) deep organisational change, some very interesting and well defined approaches to exactly the same issue in 2011 https://groups.drupal.org/node/144984

I've started a shared Google spreadsheet for inventorying the "silos":
https://docs.google.com/spreadsheets/d/1IM1a6WDS9x8WJRX3VLvGLlIa93hbsgQ-...
Anyone can view it. If you'd like to be added as an editor, either contact me using my drupal.org contact form, or private message me in Slack, and give me the email address you use with Google, and I can add you as an editor.

So, regarding #7, yes we can build views, especially if we spin up a development copy of drupal.org. I'm not entirely sure what that will accomplish right now though? I've started with that spreadsheet at least listing some of the areas on drupal.org that have different types of documentation-like content... If you can think if a view that would illuminate things, we can do that too.

Regarding #8, yes, making changes is hard. I think we have some energy/momentum to make some changes now. Complaining that we don't get stuff done is not going to help getting it done, but constructive ideas of what we can change might. Thanks!

@jhodgdon Where exactly did I complain that you or anyone else does not get anything done??? I've been most mindful to credit you and others most excellent work, please show me where I have said that and I'll gladly retract my statements.

Nice work on the spreadsheet, I fumbled around with something using markdown on groups.drupal.org but this is far superior - I have requested editor access

Another silo , appears to be well maintained and has a clear focus and audience mainly https://www.drupal.org/drupalorg/docs tho https://www.drupal.org/drupalorg

Sorry, I guess I was being too sensitive. Reading again, didn't see any complaints. Anyway, I've given you access.

Regarding the drupalorg docs, I think those are an example of documents associated with a particular project, which is listed in line 11 of the Google doc.

I think one of the problems we have is ownership.

We have situations like over at #2966481: Nuke the entire "Resource Guides" section, where @jhodgdon wrote:

> a) The Drupal Association "owns" the Resource Guides. I would not delete them without buy-in from the current staff of the DA.

We have a situation where presumably the future documentation maintainer, or a member of the docs working group can't touch documentation because it's owned by the DA.

Then with implicit ownership, there's the way that the community docs have never felt to me like the 'bold editing' environment that a wiki should be. One reason for that I think is that (as I've said before, many times), they're not actually a wiki. Changes feel to permanent, too hard to understand and too hard to revert.

> 1. Identify all of the "silos" of Drupal's documentation and answer the following questions about them:

I think we should add to this list 'What technology is it built with?' One problem we have with our silos is that lots of them are built in different ways. That makes them incompatible if we want to easily move content from one place to another.

Regarding the google doc of silos, I would:

- add the api.d.org docs, which are technically another silo. (Although one that's desirable as a separate thing)
- split the community docs into the maintained OG-based docs and the old book-based docs?
- also mention that the book-based docs have contrib modules documentation in there somewhere?
- would it get too complicated to mention the major subsections of the old book docs, such as https://www.drupal.org/documentation/build?

Would you like to make the changes that you'd like to see to the doc, or do you want me to take a try at getting them right?

Regarding ownership...

In some open-source communities, the main project's web site might be owned by the community at large and maintained by the main project maintainers, but that is not the case in the Drupal project. In our project, the Drupal Association owns *.drupal.org (they maintain the servers, the software, the configuration, etc.). Much of the content on drupal.org, such as projects, issues, and some content that has been defined as "community documentation" is owned by the community. But part of the DA's mission is to promote adoption of Drupal, and part of that mission, they own and maintain quite a bit of content on drupal.org whose purpose is marketing Drupal. The DA also currently owns some of the other content on drupal.org, such as the "Community" section, including the Getting Involved Guide -- the community doesn't currently own that section of content (which I think is ironic, but anyway that is currently the case).

The line between marketing content and documentation is not really clear. The Resource Guides, to give an example, were created by the DA staff, and when the Documentation Working Group found out about them and raised the question to the DA about where they had come from and what they were for and why they were needed, we were told (I was in the Doc WG at the time) that the Resource Guides were meant for evaluators, hence they were marketing communications, hence not documentation.

Another source of stress/conflict between the DA and the community is the software and configuration on drupal.org. The community sometimes comes up with good ideas for d.o improvements, but the community cannot come to a decision and implement it -- in the end, the DA staff has final say on what modules, views, features, etc. get onto the *.drupal.org sites. And the DA can also make changes unilaterally, without consulting the community -- and they have a history of doing so at times in the recent past.

So... That's a bit of history... I am not saying that things cannot be improved, but we *must* get agreement from the DA before we will be able to make any changes to the organizational structure of drupal.org, or remove content that the DA currently owns. We can definitely make proposals, but any decisions about drupal.org are, in the end, up to the DA.

Please don't add random tags to issues, thanks! (There are guidelines linked to under the Issue Tags field.)

> Would you like to make the changes that you'd like to see to the doc, or do you want me to take a try at getting them right?

Probably best if you make the changes you think are useful.

I'm not sure how that spreadsheet should best represent (or indeed how we should consider) the various sections that are at https://www.drupal.org/documentation/. They're all under that URL, so in one way they're all one silo. But on the other hand, once you start delving in, you encounter different layouts, things that claim to be sections, and so on. Maybe that silo alone needs its own spreadsheet?

> but we *must* get agreement from the DA before we will be able to make any changes to the organizational structure of drupal.org, or remove content that the DA currently owns.

Ok, so that's definitely a pain point!

(And it doesn't help that the DA is a body that's unaccountable and unelected...)

More generally, while I think this issue's focus is useful, I think that we've lost some of the discussion from #2956879: Proposal: Create and promote new "Quick-start guide" pages that covered things such as:

- the proposal to have a Documentation Maintainer role
- the proposal for a Documentation Initiative
- the proposal that core commits be blocked on documentation being written for changes or additions

OK, Amber created this issue with some of the "pain points", and asked for others to please add to the issue summary -- so please do!

Regarding the sections of the Community Documentation, maybe we could create a new tab within the spreadsheet to think about those sections. What columns should it have, and how would this relate to this meta-issue?

Meanwhile, I've made some/most of your suggested changes to the spreadsheet:
- Added a technology column
- Added api.drupal.org as a "silo" row
- Changed the Name entry on row 11, which already was talking about docs for individual contrib projects but you didn't realize it, so it must not have been a good name :)

I did leave the Community Docs as one row rather than splitting it into two, but I added more notes about the two systems of docs.

I'm adding the DA pain point to the issue summary. I don't really understand the ones mentioned in #20 so please expand on them and add to summary, thanks!

(And it doesn't help that the DA is a body that's unaccountable and unelected...)

We need to open a dialog with them and invite them into our discussions, how about we organise a google hangout sometime?

Also, I notice there's possibly a few projects like this https://www.drupal.org/project/emr

This project exists to help Drupal related enterprises to collaborate on better marketing of Drupal. The aim is to support the Drupal 7 release by producing marketing materials that are worthy of this big leap forward, and will help to explain the power of Drupal to clients - especially large enterprises.

Where the project has started with excellent intentions but has never been resolved, I think these projects should be closed (I will report them as abandoned as I find them) - certainly Enterprise size resources for marketing should be covered in this issue

Here's an interesting comment from a site builder

https://www.drupal.org/project/ideas/issues/2884601#comment-12533919

Are experimental modules documented anywhere? I would expect to find it at https://www.drupal.org/docs/8/core/modules and clearly labeled as experimental. In any case, the documentation should be started somewhere— just as with accessibility, 'building in' documentation from the beginning by having at least a stub added when the module is in development would help us ). I cannot find any official documentation pages for Field Layout, which has been experimental longer, and Layout Discovery, which is a full core module, could do better

So a another pain point Modules in core, even experimentally are not documented, and that documentation on drupal.org/docs or /user_guide (even a stub) should be a requirement to being merged to core

> So a another pain point Modules in core, even experimentally are not documented, and that documentation on drupal.org/docs or /user_guide (even a stub) should be a requirement to being merged to core

More generally, I would put this as: There is no process to ensure that changes in core code are matched with a change in documentation.

Which would be fixed by:

> - the proposal that core commits be blocked on documentation being written for changes or additions

As you identify pain points, goals, etc. -- please add them to the issue summary when you make your comment, rather than waiting for someone else to do it. If we find that we have some that we don't agree on, or duplicates, we can always remove them later -- better than having to comb through the comments again to try to find ones that were discussed but didn't make it into the issue summary, or worse yet, just forgetting them. Thanks!

A quick comment on #27: There is actually a documented process whereby changes in Core code are supposed to be matched with some changes in documentation -- it's called the "documentation gate". However, just because it is supposed to happen doesn't always mean it happens. And it does look like there's nothing in there saying that docs on drupal.org get updated. That's a problem. I'll add that to the issue summary.

We do have an established process in the User Guide project for making sure that when each new minor version of Drupal is released, we branch, test, and update the User Guide. Sometimes it takes a while to actually make and deploy the changes (for instance, the 8.5 branch of the user guide isn't released yet -- a few open issues we're working on), but they do eventually get done (and usually they aren't extremely large changes needed, since the Drupal UI usually doesn't change that much from minor version to version).

jhodgdon - joachim is talking about the issue from the other side of fence, he's saying that documentation of a large piece of functionality should not be merged into core - without first having some documentation in the user guide (or elsewhere?) on how to use it.

So that, in other words, it's not possible to release further new functionality in core without appropriate documentation.

However, in my opinion, this also comes back to deep organisational change

> jhodgdon - joachim is talking about the issue from the other side of fence, he's saying that documentation of a large piece of functionality should not be merged into core - without first having some documentation in the user guide (or elsewhere?) on how to use it.

@jhodgdon does mention that:

> A quick comment on #27: There is actually a documented process whereby changes in Core code are supposed to be matched with some changes in documentation

But the documentation gate at https://www.drupal.org/core/gates#documentation doesn't say anything about updating d.org user guides.

Partly that's because it's not practical to update user guide nodes before a patch is committed.

But if we had docs that were stored in git repos, we could say an issue for those with a patch must exist.

Just to point out that one of the gateways for a lot of changes is a change record, and that not all changes require further documentation: https://www.drupal.org/list-changes/drupal

I don't see a silo on the google doc for change records, so I suggest adding one.

Also: https://api.drupal.org/api/examples :-)

Neither of these is especially how-to, but important to devs. Also, if I was making a decision about whether I wanted to adopt Drupal as a technology and a community, I'd want to see change records and the availability of dev-oriented docs.

I filled in those two rows, and also the Resource Guides have been removed, so I updated that line in the spreadsheet. Change can happen!

Also there was a polite reminder from @hestenet at the Drupal Association on #2966481: Nuke the entire "Resource Guides" section to please keep the discussion on these issues constructive rather than hostile. That is always a good thing for everyone (definitely including me) to keep in mind.

Added a new row to the spreadsheet, INSTALL.txt from the actual Drupal project, this is silo number 5 (4?) of how to Install Drupal

Since we're talking about "silos" in general, and not individual documentation pages, I changed that row to be about all README type files in projects.

Ok sounds good to me, thanks

If we want to have a specific section on API docs pages, then I think we'd want to introduce an @example tag (although we should check to see if other docs systems use @example or @usage or what before we decide on the tag name).

But as things are now, there is no @example tag in Drupal docs. You can, however, definitely include usage examples in your docs. You can just do something like this:

 * Usage example:
 * @code
 * $foo = bar_baz('a', 1, [2,3,4]);
 * @endcode

If you put something like that in any documentation header for a function, method, constant, class, etc., it will be parsed and appear on the page for that item on api.drupal.org.

So there's no *technical* reason why we cannot now have usage examples in our docs, and if you want to add one to a particular page, you can definitely propose a patch and it is likely it would be accepted.

But this is unlikely to result in very much of Drupal Core to contain usage example documentation. Drupal 8.x has something like 8000 files, mostly classes, each with 1 or more documentation headers. Some are from other projects (Symfony, etc.), for which we don't alter the docs. But I think it's unlikely that the Core maintainers would agree to adopt a standard that all functions should have usage examples in their docs, so probably it's unlikely that any time soon, most functions would have usage example docs. Heck, a lot of Core has pretty much near-useless docs as it is, even though we supposedly have standards saying everything is supposed to be documented... there are a lot of classes out there that don't even have a clear explanation at the top of what the class is supposed to do, much less how/why.

In any case, I added "lacks usage examples" to the doc pain points row about api.drupal.org. :)

> I think this gap was previously filled by comments on api.drupal.org pages (practical code usage examples).

The comments still exist.

However, because of our release cycle, they are lost from view very quickly. The API module creates a new node for every class/method/function/etc each time we start a new minor branch. So the comments for a method on 8.0.x are still there, but they don't appear on 8.1.x.

(I could have sworn I filed an issue on API module about this, suggesting that comments be copied over, but apparently not.)

You did file that issue. It got moved to the apidrupalorg project (that's the custom module for api.drupal.org), since @drumm didn't think we could/should do it in the API module probably. Adding as related...

Thanks for #39 Amber!

Thanks for taking a look at this @jhodgdon (#40). So am I summarizing correctly here?

1) there are a lot of functions -- it's very unlikely we can provide examples for all/most of them
2) the best way to add examples would be in the code (as opposed to comments or references of some sort on api.drupal.org)
3) some of the code comes from upstream

I looked at the API module and it says we are using doxygen, which AFAICT uses @code/@endcode for a few lines of code and @example for including a whole class or file (and has extra work around including paths; excluding example code from the docs, etc) -- https://stackoverflow.com/a/8985160 and http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdexample

Would it be possible to get usage statistics from api.drupal.org on the most popular functions?

So next steps could be:
1) submitting some patches w/ @code/@endcode to popular functions
2) possibly making some updates to the api module

We are only kind of using Doxygen. As it says on the API project page:

The API module implements a subset of the Doxygen documentation generator specification, with some Drupal-specific additions. Standards for how to write Drupal documentation that this module can parse (and that conforms to Drupal coding standards) are on http://drupal.org/node/1354.

We do not support @example at this time. We do support @code/@endcode. We also have the ability to make cross-links. If we need more functionality to support the kinds of examples you think we need, we can definitely consider adding it to the API module, but up until now (and some functions do have usage examples), what we have has been enough.

I don't know about usage stats on api.drupal.org.... I think for Drupal 8, a large subset of the developer community has switched from using api.drupal.org to using IDE software, so having the examples right in the code becomes even more important -- they would never see the comments.

As one other note, there is one way to get usage examples on api.drupal.org, which is the "34 functions call this function" and similar sections of links on many pages. Like this example:

this will link you to other places in Core that use that function.

Seems like a good idea to ask at least. You could file a Core issue, or maybe in Ideas, to make that suggestion.

It would be even quicker though to just ask people to put a link to the change record into the code. Sometimes figuring out what to extract from a change record to put in the code would take some effort, but putting in a link costs virtually no effort.

What happened to the comment someone made listing pain points in the OG-based docs? There was a suggestion to file a separate issue but I don't think that's been done.

Cat's are out of the bag https://www.drupal.org/node/2972473 :(

If you can find that comment (was it comments here or in the other issue this spun off of?), feel free to make another issue. Or another tab in the spreadsheet. For now, there's one line in the spreadsheet about the Community Documentation that lists some of the pain points that I located in the comments here, but if we need more, yes let's file an issue.

Scrolling through https://www.drupal.org/governance/doc-working-group it seems like addressing a good bit of these pain points would be in-scope with the mission/goals of the Documentation Working Group.

If so, possibly looking at ways to enable/expand the working group could be key to resolving many of these issues?

Keep in mind that the Documentation Working Group is meant to be a governance group -- their main role is to make decisions and set direction rather than fix issues.

So, in regards to this issue, if someone suggested that the best way to resolve some pain point would be to eliminate one of the "silos", the DocWG should probably finalize that decision, but they might not be the ones to actually do the work of making sure the content got migrated, consolidated, etc.

For this issue, I think we're currently at the point of identifying pain points, rather than even trying to resolve them.... I have made a survey of the "silos" of documentation, but I don't even know if anyone has looked at it, validated whether the pain points of each silo have been identified, etc. Much less suggested any solutions.

I should have specified after reading over the scope/duties/responsibilities described in the Documentation Working Group Charter, it seemed like the DocWG could play a key role in providing clear and obvious guidelines, policies, and processes. Just this alone would really help -

Coordination and collaboration: The DocWG will work with other governance bodies on areas of common interest and overlapping responsibilities; for example, to ensure that there is a consistency of user experience and style across the documentation and non-documentation areas of drupal.org.

From what I can gather, the DocWG isn't really active in the day to day coordination, identifying needs, onboarding contributors, and facilitating collaboration. Most likely we could sustain an ongoing leadership team if we unify some of the ongoing projects, initiatives, and overlapping working groups.

Based on discussions in #documentation today -

An update regarding status of the Docs WG...

...that page needs some updates. the Docs WG hasn't had any meetings in quite a while, and as a group isn't really working on anything specific. We've actually been trying to shuffle things around a bit and get some new people on the working group who have more time/energy to work on the things listed....

...and then later learning the same Documentation Working Group is driving the Documentation Initiative.

I'd say getting the Docs WG to the point where there are "3-5 members of the Drupal community who are active in the documentation field, to ensure that the decisions made within the DocWG are in harmony with the people contributing to on-line documentation."... would be a priority.

> If you can find that comment (was it comments here or in the other issue this spun off of?), feel free to make another issue.

Argh, I can't find it!
It's not in this issue, or on #2956879: Proposal: Create and promote new "Quick-start guide" pages.

I remember it was a comment by someone new to that issue, who made a list of points, and then someone, possibly @jhodgdon replied saying they should file an issue on the d.org project listing those, and I meant to follow up and add a few points of my own...

I think, but I might be wrong, that you are looking for my comment. I haven't had time to create a separate issue for it - busy at my paid job.

@hansfn brilliant, thanks! I've made that issue: #2973777: [meta] Identify OG-based documentation pain points

Great, thanks for creating that! I've added that issues as Related to the community documentation in the Documentation Silos spreadsheet linked in the issue summary
https://docs.google.com/spreadsheets/d/1IM1a6WDS9x8WJRX3VLvGLlIa93hbsgQ-...

I think the Drupal documentation should take an example of the Symfony documentation: step-by-by-step instructions in handbook style.

Clearly initialized by an Sensio and Fabien Potencier. It is obvious that it has been funded and lead by one person. E. g. https://symfony.com/doc/current/forms.html

The "disabling Drupal cache during development article" is like that: https://www.drupal.org/node/2598914. However, most Drupal devs are needing this article. So it is revised good.

The most other article are like knowledge spots. Tiny pages with just some info. No instructions and examples in a handbook style. Written by many people, covering just a small part of the functionality, no straight forward step-by-step instructions: that's confusing. You end up googling.

It takes a lot of time to write down all this instructions with examples. So there should not work many people on 1 page the same time. Because then this page is a knowledge spot again.

This work should get funding. Excellent coders, with wording skills should get paid to write down the instructions within a deadline.

Otherwise this effort is again a structuring/restructuring job, which does not help much.

In order for content (and contributors) to be consistent and effective, I think priority docs projects and initiatives should be unified under one Documentation Initiative with oversight from the Documentation Working Group.

A couple reasons include -
- many of the current leads are already collaborating on multiple projects and working groups
- they've also created a detailed guide that can serve as framework for coordinating any ongoing documentation project
- resources (contributors and funds) could be pooled
- communication, marketing, outreach, etc. could be streamlined
- would make it easier to connect and collaborate with other groups for onboarding, mentoring, training, events, etc.

Would this be possible?

Agree w/ Gusaus. Would be nice to see priorities under the tag "Documentation Initiative" to consolidate searches, and have oversight from DWG. In fact, I'm pretty sure the latter part is already in place :) Joe and Jennifer have already commented on multiple issues and have provided guidance to several of us contributing.

As for the former, we just need to get better at tagging stuff.
-Shan

Thanks @svettes

I think it's still difficult for contributors (especially newcomers to documentation or Drupal) to even know where to start. As far as I can tell there's nobody from the docs initiative or docs working group actively greeting and onboarding newcomers to #documentation Slack. It's probably daunting for a lot of folks to just join a google hangout and chime in. It's good to see a post about the initiative on https://groups.drupal.org/documentation, but who knows how many people even think to go to https://groups.drupal.org/ these days. It doesn't seem like there's a lot of activity on social media regarding who's doing what or how to get involved.

Possibly there still a need for someone to handle outreach, onboarding, and social media? Are there other roles the docs initiative and working group are looking to fill?

Further reading for anyone interested: Stripe (the payment processing company) publish a free online magazine called Increment, the latest issue of which is all about documentation.

After the BoF at DrupalEurope and now having a better idea of how to tidy up /community, I’ve created a project especially for that job, at https://www.drupal.org/project/drupal_org_community

Great! You might want to reference this in some of the Related issues that are listed on the sidebar here, or move them into that project. I'm thinking of the "Create community section" and "Create contribute section" issues.

Yes - absolutely!

I was commenting on #2973161: [policy, no patch] Add link to change record in code comments 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.