Come together with the global Drupal community in Rotterdam, 28 Sept – 1 Oct 2026. Sessions, contribution, connection, and Early Bird savings until 8 June.Hi all
Background: About 3 weeks ago I decided to finally go full deep into really learning Drupal 8, I spent 2.5 weeks of that being basically stranded in the routing system section of the API documentation due to relatively small pieces of information missing. (I made several (dozens?) of edits and really tidied up that section.)
Then I realised, hang on there's a User Guide and Drupal 8 Documentation, so I moved onto the multilingual part of my project.
The Issue: And then I realised, the Drupal 8 Documentation seems to contain a lot of out of date information about how to USE core functionality, not at all related to doing any API work, the information presented in the Drupal 8 Documentation is often out of date, poorly formatted or a complete duplicate of existing "official" user guide information.
My current gripe is the Multilingual section
I've created a shared google diagram here
So essentially
- What is the "truth" here for people coming to Drupal 8? Is it the Drupal 8 Documentation docs or the User Guide?
- When the Drupal 8 Documentation contain information about configuring core modules that is already covered in the User Guide, can I go ahead and delete in entirety that information from Drupal 8 Documentation, because it's likely to be out of date and unofficial?
- What specifically is the goal of the Drupal 8 Documentation? Is it for DEVELOPERS or SITE BUILDERS?
- Can we make the differentiation in the previous point more obvious and tightly controlled? I'm happy to start purging documentation from the Drupal 8 Documentation that is already covered in the User Guide
My general feeling of the "Drupal 8 Documentation" section is that it's missing a "goal", where this is nice and clear in the User Guide, I don't really see the point of most of the multilingual site.
Hope this helps!
| Comment | File | Size | Author |
|---|---|---|---|
| #4 | Screenshot_2018-04-25_16-48-06.png | 74.41 KB | dgtlmoon |
| Drupal multilanguage config wtf docs.png | 187.13 KB | dgtlmoon |
Comments
Comment #2
dgtlmoon commentedComment #3
dgtlmoon commentedComment #4
dgtlmoon commentedComment #5
dgtlmoon commentedComment #6
joachim commentedThis is a completely valid criticism, but a small nitpick: by 'API Documentation', we usually mean documentation that's on https://api.drupal.org/api/drupal, which is stored in drupal's own source code. That doesn't seem to be what you're referring to here.
Comment #7
dgtlmoon commented@joachim yes you're right, I will update the issue, I guess I always refer to "Drupal 8 APIs Documentation" in this case, terminology is highly important!
Comment #8
dgtlmoon commentedComment #9
hansfn commented@dgtlmoon: You missed joachim's point in the comment about API. The Drupal API documentation is located at https://api.drupal.org/ It is about programming Drupal using it's API. The documentation found on for example https://www.drupal.org/docs/8/multilingual is the community documentation - or wiki if you like. If you call it "Drupal API documentation" no one will understand this issue.
Anyway, the problem you have discovered is being discussed in the documentation initiative - see https://www.drupal.org/project/ideas/issues/2956879
Comment #10
joachim commented> wiki if you like
It's not a wiki though. 'Community documentation' is clearest.
Comment #11
jhodgdonSee also this related issue...
Just FYI, there is a section of the Community Documentation that is called "Drupal 8 API documentation":
https://www.drupal.org/docs/8/api
and I think that is what the issue here is referring to. That section should not contain docs on how to set up sites, it should all be API information that is longer than what is on https://api.drupal.org -- if it isn't that, we should move some of that documentation out of that area and put it somewhere else.
But yes, we also need to remove information that is duplicated between the User Guide and other places in the Community Documentation...
Comment #12
dgtlmoon commentedComment #13
dgtlmoon commentedComment #14
dgtlmoon commentedOk, Sorry for the confusing issue description again - I've updated the issue, it's confusing even just trying to write about the current state of documentation without loosing ones mind.
@handsfn
if this really is "community documentation" or "a wiki if you like", then can we please LABEL the damn thing as such? and provide links to OFFICIAL DOCUMENTATION
I cannot begin to describe how insanely frustrating learning Drupal 8 is when you have 3 different main silo's of documentation which are in a varying state of disrepair
Drupal 8 Documentation || Resource Guides || User Guides
How is anyone meant to know what todo here?
Take a look at other projects, Vue.js and Symphony both push the "one message" approach.
I completely appreciate the work the Documentation team does - but I'm saying that the whole "Resource Guides" section should be completely scrapped as a whole, no one has touched resource guides for over 5 years and it still refers to Drupal 7 !
Start culling any OLD general documentation from Drupal.org, focus on making "user guides" the biblical truth, and let occasional drupal devs like myself start nuking old content that has polluted the "Drupal 8 Documentation"
On that note, can we rename "Drupal 8 Documentation" to something ELSE? It's also really confusing terminology.
Who is "Drupal 8 Documentation" aimed at? why is it called "Drupal 8 Documentation" and you also have "User guides" ?
Comment #15
jhodgdonAs I said in comment #11, this confusing situation is already being discussed on #2956879: Proposal: Create and promote new "Quick-start guide" pages. I think that this issue here should be closed as a duplicate. People have identified the same problems that you're pointing out here on that other issue, and are calmly discussing what can/should be done there, so if you have constructive comments to add, I suggest you make them there. Your discussion here is coming across as anger and ranting... I understand that you are frustrated, but ranting about the problem is not going to help it get solved, or make anyone want to take your points seriously.
Also, I would just like to point out that there is no "documentation team" in Drupal per se. There are a number of people who occasionally volunteer to write or maintain community-provided documentation pages, but there is no one who is paid to maintain the documentation. What you're asking for should probably be done. The problems are (a) agreeing on exactly which pages should be reorganized or deleted, (b) agreeing on how to reorganize them and (c) finding someone to actually make it happen.
Comment #16
lizzjoyI updated the issue summary to remove Resource Guides-related comments. They have been nuked and now redirect to industry pages.
Comment #17
avpaderno