Currently documentation pages for Drupal core modules have urls "d.o/documentation/modules/[title]". Links to documentation pages using those urls are present in the Core itself. On Drupal.org these documentation pages are located all over the place, in different 'books', or different parts of the same book. All of them are listed at: https://www.drupal.org/node/1283408.

With the new documentation system in place there are a few changes that affect this url structure:
1. All documentation pages get human-friendly urls. They are created automatically, and are based on the location of the page in the documentation section IA to ensure predictable and cohesive system of urls.
2. Documentation is split by major version, so that Drupal 7 documentation is separate from Drupal 8.
3. All documentation for core modules will be located in a single place (per version) Drupal 7/8 -> Core -> Core modules:
Drupal 8 core modules documentation https://www.drupal.org/docs/8/core/modules
Drupal 7 core modules documentation https://www.drupal.org/docs/7/core/modules

This means that, for example, documentation for core dblog module will be located at:
https://drupal.org/docs/7/core/modules/dblog for D7 version
https://drupal.org/docs/8/core/modules/dblog for D8 version

While the old urls "d.o/documentation/modules/dblog" will continue to work as redirects, they can only redirect to a single document so either D7 or D8. Which means that links from one of the versions of Core will go to the wrong version of documentation.

Next steps

  1. Migrate documentation to the new system first, to ensure we have all the links ready before updating them in Core
    Status: Done, except for C below
  2. Ensure all old urls e.g. "d.o/documentation/modules/dblog" redirect to D8 version of the documentation. Even if a module is not in Core any more, still redirect to the 8 URL (which will be in the contrib section)
    Status: done, except for B below.
  3. Ensure every D8 page has relevant D7 page added as 'Related content'.
    Status: somewhat done, a 2nd pass would be good.
  4. Update urls in Drupal 8 core to link to appropriate doc guides e.g. drupal.org/docs/8/core/modules/[short-name]
    Status: Blocked on A and B below. - Work to be completed in #2855175: [META] Many documentation / handbook URLs redirect to D7 content
  5. Update urls in Drupal 7 core to link to appropriate doc guides e.g. drupal.org/docs/7/core/modules/[short-name]
    Status: Blocked on A and B below.
  6. Update URLs in Contrib documentation for modules that are in Core in some versions of Drupal and Contrib in others to point to correct URLs.

A. Currently not in the proper location:

This documentation is located outside of the central core modules area d.o/docs/8/core/modules, and thus it does not have the proper urls of the type docs/8/core/modules/X. It either needs to be moved, restructured, or redirects set.

B. Drupal 8 version needs to be created + currently not in the proper location:

This documentation only exists in D7 version, D8 version needs to be created.
Before D8 version can be created, we need to know where to put it (see below).
This documentation is located outside of the central core modules area d.o/docs/8/core/modules, and thus it does not have the proper urls of the type docs/8/core/modules/X. It either needs to be moved, restructured, or redirects set.

C. Not migrated:

CommentFileSizeAuthor
#42 Screen Shot 2017-03-15 at 9.21.13 AM.png294.2 KBNonProfit
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

tvn created an issue. See original summary.

eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
CreditAttribution: eojthebrave at Drupalize.Me commented

This seems like a good plan to me. Redirect to D7 URLs for now. The D7 pages can have a "related page" for the D8 version so if you end up on the D7 one it's easy to make your way to the right version. And then we can update all the URLs in the code for D8.

In theory I would think we can update these URLs in Drupal 7 as well. If they're part of the documentation in PHP then if they are wrong it's a bug, and we can fix bugs in documentation. If they're used anywhere in the UI we might have to look at those on a case-by-case basis, but I bet even those can be fixed if we deem them "wrong".

tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented

Thanks, Joe. We can update urls in D7 core for sure. I suggested D8 only initially purely to have less work, so that migration wasn't blocked on numerous core patches.

I'll ping a few more people to give opinions and then probably open an issue(s) in the Core queue.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Hm... I would think, in principle, that having the redirects go to the d8 URLs would make more sense, so that if someone has the page bookmarked, they'd get to the D8 version, rather than an outdated version? We can patch d7 just as well as d8, and probably we should patch both.

Right now the pages are the same for d7 and d8 anyway, right?

Some of the pages are Core in one version and Contrib in another though... I guess you probably know that. Such as Views. I think there was a module or two that was core in D7 and is now contrib in D8 too, but I can't think of what they are.

hansfn’s picture

hansfn CreditAttribution: hansfn commented

The blog module moved from (D7) core to (D8) contrib - https://www.drupal.org/project/blog There was one more, I think.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Right! The poll and profile modules in D7 seem to be gone in D8... and a few more:
https://www.drupal.org/project/poll
https://www.drupal.org/project/profile
https://www.drupal.org/project/dashboard
https://www.drupal.org/project/openid
https://www.drupal.org/project/php

I think that is most/all of them...

tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented

Okay, so when a module is in contrib in specific version, documentation for that version will be located in /docs/7[8]/modules and we don't need to worry about those. I assume when a module is not in Drupal core, there are no links in Core to its documentation to update there.

I have no preference on where redirects should go, if you prefer D8, let's do that.

Right now the pages are the same for d7 and d8 anyway, right?

Yes, I haven't migrated those yet. Right now it is a mix. Sometimes there are separate pages per version, sometimes information for different versions is on the same page. They will need to be split during migration.

tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented
Issue summary: View changes

Updated next steps in the issue summary. Does that sound like a good plan?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes

Contrib modules' hook_help() would also presumably have links to the drupal.org docs pages, if they follow our templates, so even if a module is not in Core for one version of Drupal, there still may be links that need to be updated.

Given that, I am not sure we should adopt the "if it's not in Core, go to the D7 page" step. Maybe it should still go to the D8 page, but the D8 page should be under contrib docs?

I fixed a typo in the summary (didn't change for the above suggestion)... but I think we should change the next steps to say:

- (amended item 3) Even if a module is not in Core any more, still redirect to the 8 URL (which will be in the contrib section).
- (new item at end) Update URLs in Contrib documentation for modules that are in Core in some versions of Drupal and Contrib in others to point to correct URLs.

tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented
Issue summary: View changes

Makes sense to me. Updated the summary per your suggestions, jhodgdon. Will ping Joe to see if he has any more opinions on this.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Looks good to me!

tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented
Issue summary: View changes

Okay, I will start working on the 1st step then.

tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented

Update: I migrated all of the content that was under 'Core modules' part of the Site Building guide (https://www.drupal.org/node/1283408).
There are now:
- Drupal 8 core modules guide: https://www.drupal.org/docs/8/core/modules
- Drupal 7 core modules guide: https://www.drupal.org/docs/7/core/modules

However, as I go through the list at https://www.drupal.org/node/1283408, there are other documentation pages about core modules, which are located all over the place: in the Site Building Guide, under contributed modules, in "generic" documentation e.g. standalone "Working with comments" guide, etc. I am going to attempt to collect all of that documentation in the two centralized locations per version as much as possible.

Another question is: what should we do about the page https://www.drupal.org/node/1283408 itself? Is it useful?

tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented
Issue summary: View changes

Adding a list of core modules that currently have their docs elsewhere.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

So, a bit of history... At some point in the past, an attempt was made to organize the documentation on drupal.org by tasks someone might want to do. That is why the Core module documentation is all over the place. For instance, if you found the core module page about the Forum module, you would find the contrib Advanced Forum module documentation nearby, and possibly also a page comparing different options for building forums -- all of the forum-related documentation would be together.

The current plan of putting all Core module documentation together is not very reader-oriented or task-oriented -- it is instead organized by the software. So unless all three of these pages in my example had "related pages" links on them, there wouldn't be a good way for someone to find all of them, or discover that the related documentation exists after finding one of the three pages, except by combing through a long list of search results. To me, this seems like a step backwards, although I freely acknowledge that the previous documentation on drupal.org was not really possible to navigate... at least sometimes, related pages were grouped together though.

Or in your example of "Working with comments", are you going to break up that section by moving one page that happens to be about the Core comment module out? That doesn't seem like a great idea.

Anyway... I guess this decision has already been made. But when these pages are moved, I hope that the relationships to other nearby pages are being preserved somehow.

Regarding that page that shows all the core modules, if we're already organizing documentation into a Core Modules section, it doesn't seem all that useful to have a page listing them all like https://www.drupal.org/node/1283408 -- it seems like it is obsolete.

tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented

Thanks for that background Jennifer. I think organizing docs by the task is a good idea in general. In our case I think the problem was that it was only half done, e.g. some bits were in a centralized 'core modules' area, some were in 'task' areas, some were in an clearly wrong places (e.g. when under 'contributed modules for x' you have a core module). It seems that organizing by task is easier in a curated environment, e.g. D8 User Guide, where you have an opportunity to plan, decide what are the actual tasks you want to cover, what is the structure, and then stick to that plan. Whereas when it is a community documentation, people end up putting documentation in random places or create duplication, because they don't necessarily know what's the plan and which place is the correct one. I think in this case organizing by software might be easier from maintenance standpoint, because then everyone (who writes docs) knows if it is a core module - docs go here, if it is a contrib module - they go here.

For those reading docs, I don't think they care /how/ pages are connected to each other, as long as they can find them. We do know that people rarely navigate docs from top level page down until they find what they need. Mostly they come from search right at the page which matches their search terms. We then should provide ways for them to get to relevant related content. I definitely agree that everything should be connected via "Related content" otherwise the whole thing does not make sense.

So I think we'll end up having some general documentation about common concepts and tasks (D8 User Guide is a good example), which then links to a more detailed docs for a particular module.

I personally don't have any strong preference on how the top level buckets under /docs/7 or docs/8 should be structured. We're open to any changes you / DocsWG want to propose.

What I do want to ensure though is consistency and predictability. E.g. if core modules docs are located under docs/7/core/modules, then *all* core modules have their docs there. If it is decided they should live elsewhere, then *all* core modules docs should live elsewhere. If a page has a url, for example, /documentation/modules/views then the page one level above it in the hierarchy is /documentation/modules and not something else.

Or in your example of "Working with comments", are you going to break up that section by moving one page that happens to be about the Core comment module out? That doesn't seem like a great idea.

That is a good question. Part of why I posted my update was exactly so we could discuss it :) because I don't necessarily know. I think it will be a section by section thing. Sometimes /the whole section/ is about a core module, then it can probably be moved all together. When a section has a lot of general documentation content and just one page happens to be about a core module, I think we move that one page and connect it to the rest of the section via a 'Related content' field and direct links from the other pages copy. Perhaps sometimes it would make sense to have a short page under core/modules/ saying something like "Field UI is a UI for.... Find more information on how to use Fields at [link to general docs]".

tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented
Issue summary: View changes

For now I am moving the ones that were in Contrib modules section and weren't migrated yet.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

So, we need to have a unified URL structure for module documentation, which is one thing. But how the pages are organized into Guides is another question, and doesn't have to be correlated, does it?

tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented

Well, those two are kind of connected. URL structure represents the IA structure and thus the location of things. So e.g. if a page has a url /documentation/modules/foo and another page has a url /documentation/modules/bar, it is expected that the two pages are located under 'Modules' in the hierarchy of pages, and the 'Modules' is located under 'Documentation'. If you open /documentation/modules/bar and see that its parent is say 'Understanding Drupal' instead of 'Modules', and all of the breadcrumbs don't match the url structure at all it is confusing.
For the new content types this is also automated, as in all guides and all pages get human-friendly urls automatically based on their location in the guides structure. E.g. d.o/docs/[top-level-guide: D8, D7 or Develop]/[parent guide]/[page-title]

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I see... but in this case, we want/need the landing pages for core and contrib modules to have a uniform URL structure because they are linked to from inside Drupal core/contrib software (in the provided Help topic). I guess those could be redirects though. I still think that doing things like separating out a section on managing forums or comments or whatever by moving the page about the Core module into one Guide, and the contrib modules each into their own Guides, would not be helpful.

Here's an example of this type of fragmentation:

a) There's a section in the docs about modules for forums:
https://www.drupal.org/node/1691400

b) Underneath it are sections about the Advanced Forum contrib module, and Harmony Forum, which is both a distribution and a contrib module. Both of them are for Drupal 7.

c) Then completely separate, we have sections for the core Forum module for Drupal 7, and for Drupal 8:
https://www.drupal.org/docs/7/core/modules/forum
https://www.drupal.org/docs/8/core/modules/forum
These two are linked together in Related Documentation, but if you did a search for them, both of them would have the title "Forum module", and you would have no idea (unless you looked at the URL) that one was for Drupal 7 and one for Drupal 8. That is also a problem.... if we're going to separate them out into 7 and 8, we should definitely have 7 and 8 in the page titles because when people scan search results, the most prominent thing displayed is the page title (whether using d.o or Google or anything else).

I think before these two pages were migrated, there was only one page that covered both 7 and 8 (and 6 for that matter), so the title of just "Forum module" made sense.

Also these two pages are actually unlikely to come up in searches because they are completely devoid of content... So the sub-pages also need to have better titles too, with the version number in them.

Anyway... To me the URLs are mostly irrelevant -- that is possibly because I am used to URLs on drupal.org being mostly irrelevant, not to mention on other sites. Many browsers these days even hide the URL bars by default, or make them small so you can't see the whole URL anyway -- I just don't think most sites on the Internet have useful URLs (they tend to be so long no one would look at them). We do need standardized URLs for the core modules (and contrib too I think) so that we can put the URLs into the code. And we have some legacy URLs out there that we need to either maintain or redirect, so links are not broken. But any other URL structure I just think is a waste of time to worry about.

What people are really going to see is the page titles (these are especially important because of search results), and the breadcrumbs, and the sidebar menus. And possibly the "Related content" sections at the bottom of pages (are those for Guides or also for Pages?), but as those are at the bottom of the page, they will be less prominent than the other stuff. So I think we need to get those right, and make it so people, once they find one somewhat relevant page or are looking at a list of search results, can quickly find the content they actually need. That should be the focus.

tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented
Issue summary: View changes

Step 1 is almost done, I migrated most of the pages, the only remaining one is Views.

tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented

I see... but in this case, we want/need the landing pages for core and contrib modules to have a uniform URL structure because they are linked to from inside Drupal core/contrib software (in the provided Help topic).

Yes, and they will.
For core modules: drupal.org/docs/[8|7]/core/modules/[short-name]
For contrib: drupal.org/docs/[8|7]/modules/[short-name]

If we're going to separate them out into 7 and 8, we should definitely have 7 and 8 in the page titles because when people scan search results, the most prominent thing displayed is the page title (whether using d.o or Google or anything else).

I agree that we need to provide version information in the page title. I don't think however that it needs to be in the /node/ title, manually entered by people. We already have this meta information about every page, based on its location in the docs hierarchy, we just need to make sure we display it and include it into page title via token. I'll open a separate issue for this, cos its a bit offtopic for the current issue.

"Related content" sections at the bottom of pages (are those for Guides or also for Pages?)

You can add docs guides, docs pages, change records, pages or posts as Related content.
We might consider moving 'Related content' to sidebar to make it a bit more prominent.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Sounds good. My question was really whether the Related Content is a field that is on both Guides and Pages.

tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented

My question was really whether the Related Content is a field that is on both Guides and Pages.

Ah, sorry, yes on both guides and pages.

tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented
Issue summary: View changes

I migrated Views docs, which means everything that exists was migrated. Updating the issue summary with statuses, etc.

tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented
Issue summary: View changes
tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented
Issue summary: View changes
tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented
Issue summary: View changes
tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented

Forgot to assign this issue to myself earlier, so can't unassign now, but I need to focus on other things for the next few days. My personal opinion on A and B from the issue summary is that since docs for like 80% of the modules are in the central locations, we need to have /some/ representation for all of the modules there. Connected to 'general' documentation in whatever way makes sense.

NonProfit’s picture

NonProfit CreditAttribution: NonProfit at GoGrow.org commented

Hi, I'd like to help with this issue. Where is the best place for me to jump in?

eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
CreditAttribution: eojthebrave at Drupalize.Me commented

It seems like the next step for this issue is probably to work on creating pages/guides in https://www.drupal.org/docs/8/core/modules for each of the core modules that do not already have a page. Which, looks like they are listed in the issue summary. And that creating those pages is going to entail some combination of, copying and editing the Drupal 7 version of the page, writing new content from scratch, and using the "Related content" field to link to other already existing pages in the documentation that we want to reference, but not move out of their current context.

So, for each module we need a guide added to https://www.drupal.org/docs/8/core/modules, and at least one documentation page added to the new guide.

I'm guessing each one is going to end up being a bit different. But, at a minimum we should have an overview page with a paragraph or two about the module and links to other relevant content. The book module's guide is a good example I think https://www.drupal.org/docs/8/core/modules/book

Maybe if you want to work on this you can claim a module by putting your name next to it in the issue summary and get started creating the content. Lol, at least that seems like a logical plan to me. I'm open to other ideas though. :)

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

If you are a module maintainer, you can easily migrate your documentation. Edit your project, and scroll down to the vertical tabs at the bottom. Find the Project documentation section. Follow the steps there. I found it to be fairly straightforward, for at least one module that I maintain.

If you're not a module maintainer, then this issue may not be the best place for you to contribute to documentation... unless there is some module that you use a lot and are familiar with enough that you can convince a module maintainer to add you as the documentation maintainer for that module?

However, you can still help with other documentation! There are plenty of pages of documentation that also need maintainers, that are not connected with any particular module. See this issue:
#2682083: Recruiting guide maintainers for documentation

NonProfit’s picture

NonProfit CreditAttribution: NonProfit at GoGrow.org commented

eojthebrave and jhodgdon, thanks for your replies.

I have a solid working knowledge of D7 and 8, but I am certainly not schooled in the nuances of every module's differences.

At this point there are at least three dozen links in D8 core which redirect to D7 handbook pages (https://www.drupal.org/node/2855175). Supplying new links is trivial, but in many cases the D8 documentation has not been created. Is it best to wait on that until the handbook is more complete, or could we create placeholder pages?

Thanks!

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Oh... sorry. In my previous comment #32, I was thinking about *contributed* modules, not *core* modules. Disregard what I said there!

So eojthebrave in #31 is correct. If a page for D8 has not been created for a core module, then we need to create one, and if you want to do that, great!

Initially, the page can contain one of the following:

a) The D7 content -- in many cases, the functionality of the module is the same
b) The Help page that you see within a Drupal 8 site if you enable the module (and have the Help module enabled too).

If the content comes from D7 and needs updating, you can use the Page Status taxonomy field to indicate that the content needs review, and/or put a note at the top saying something like "This is the D7 content and it needs to be updated".

Thanks!

NonProfit’s picture

NonProfit CreditAttribution: NonProfit at GoGrow.org commented

jhodgdon, sounds great; I'll try to get started in the next few days. Thanks.

NonProfit’s picture

NonProfit CreditAttribution: NonProfit at GoGrow.org commented

OK, I created https://www.drupal.org/node/2859827, but unless I'm doing something wrong, it looks like I can't add child pages to it because it has not been approved.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Hm. It looks like https://www.drupal.org/node/2859827 is a Documentation Page, and not a Documentation Guide. Only Guides can have child pages; their children can either be Guides or Pages.

I'm not all that familiar with the procedures for creating new documentation pages/guides right now, but it does definitely look like this is a Page and not a Guide, so that is probably why you cannot add any child pages.

NonProfit’s picture

NonProfit CreditAttribution: NonProfit at GoGrow.org commented

jhodgdon, thanks much for your update. I'm not new to Drupal documentation, but I'm stumped as to how to create a guide or even delete the page I created. Thanks.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Hm.... I don't know much about this process either, and tvn is probably not in charge of it any more, considering she is no longer at the Drupal Association... So, bear with me... Maybe @eojthebrave knows more?

So... It looks like if I start at
https://www.drupal.org/docs/8/core/modules
I can click on "Documentation Guide" under "Add Content" in the right sidebar. Do you have that link? (I have some elevated content permissions on drupal.org, so I never know if what I see is what you see). That seems like the right way to create a new Guide.

How did you create your documentation page?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Meanwhile I went ahead and deleted the page you had previously created... having content admin permission must be good for something! :)

eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
CreditAttribution: eojthebrave at Drupalize.Me commented

Yeah, that sounds right to me. Anyone who can add content should be able to create a new documentation guide, or a new documentation page. You can read more about the difference between the two here https://www.drupal.org/drupalorg/style-guide/words-phrases/content-types...

And, I would also agree that adding a new guide for each module to docs/8/core/modules, and then as many pages to each of those guides as is required is the right approach here.

NonProfit’s picture

NonProfit CreditAttribution: NonProfit at GoGrow.org commented
FileSize
Screen Shot 2017-03-15 at 9.21.13 AM.png294.2 KB

Hi, thanks for the info. I may be incorrect, but I don't believe I have the permission to create a Guide. When I visit https://www.drupal.org/docs/8/core/modules, I'm not noticing a way to add content. When I'm on a page like https://www.drupal.org/docs/8/core/modules/action, I have a link to create another Documentation Page.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I see what you are saying. I have a section below what you have on the sidebar, that lets me add a Guide to the page.

I am not sure what the strategy plan is for that. If ordinary, confirmed users cannot add new Guides, then how do they get created? I could add one or more of them for you, but it seems like we need to resolve the permission problem first. I'll try to find out where I should file an issue or what the philosophy is and report back... sorry about that!

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

OK, I think we have resolved the current problem!

It turns out that you needed to be added as a Maintainer of the Drupal 8 Core Modules page. @drumm has taken care of that, so @NonProfit, you should now be able to add Documentation Guides as children of that page. Thanks again for wanting to help!!

Meanwhile, I have also filed #2860875: Permissions plan for Documentation Guide and Page content (which references this issue and should be linked in the sidebar here under Related Issues) to discuss the larger permissions issues.

NonProfit’s picture

NonProfit CreditAttribution: NonProfit at GoGrow.org commented

jhodgdon, thank you!

tvn’s picture

tvn CreditAttribution: tvn commented

Sorry for being away, seems like you got it sorted anyway. Some documentation on using the new system can be found here: https://www.drupal.org/drupalorg/docs/content/documentation.

eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
CreditAttribution: eojthebrave at Drupalize.Me commented
Issue summary: View changes
blakehall’s picture

blakehall CreditAttribution: blakehall at Drupalize.Me for Drupalize.Me commented
Issue summary: View changes

Added a stub for the Configuration manager module that links to the configuration management guide.

blakehall’s picture

blakehall CreditAttribution: blakehall at Drupalize.Me for Drupalize.Me commented
Issue summary: View changes
blakehall’s picture

blakehall CreditAttribution: blakehall at Drupalize.Me for Drupalize.Me commented

Breakpoint module stub added here: https://www.drupal.org/docs/8/core/modules/breakpoint-module/breakpoint-...

ddavidd’s picture

ddavidd CreditAttribution: ddavidd commented
Issue summary: View changes

I completed the contextual links guide and removed it form the list: https://www.drupal.org/docs/8/core/modules/contextual

purplenwu’s picture

purplenwu CreditAttribution: purplenwu commented
Issue summary: View changes

I updated the Help Module for Drupal 8: https://www.drupal.org/docs/8/core/modules/help#comment-12019222

ddavidd’s picture

ddavidd CreditAttribution: ddavidd commented
Issue summary: View changes

Added the toolbar page.

hansfn’s picture

hansfn CreditAttribution: hansfn commented

I just moved https://www.drupal.org/docs/8/core/modules/breakpoint-module/ to https://www.drupal.org/docs/8/core/modules/breakpoint which seems to be the correct URL pattern

Two questions:

  1. Why are some (non-experimental) modules not sorted alphabetically on https://www.drupal.org/docs/8/core/modules? Hm, maybe the order of sub-guides is available only to maintainers.
  2. Regarding A and B in the issue summary: Is it just to go ahead and solve it as good as possible or should we continue the discussion that tvn and jhodgdon had 4 months ago. I lean against just doing it.
eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
CreditAttribution: eojthebrave at Drupalize.Me commented

Why are some (non-experimental) modules not sorted alphabetically

The sorting is based on the menu item weight. This can be controlled by anyone who is a maintainer of the section. I'll see about re-ordering it when I get a chance, or happy to add you as a section maintainer if you would like to assist.

Regarding A and B in the issue summary: Is it just to go ahead and solve it as good as possible or should we continue the discussion that tvn and jhodgdon had 4 months ago.

I'm not sure that I understand what part of the discussion you're referring to. I believe the issue summary is up-to-date as far as next steps go. Are you wondering about the decision to organize things based on module vs. task? Or something else?

hansfn’s picture

hansfn CreditAttribution: hansfn commented

Yes, the discussion about module vs task - comment 15 and on. We all agree that there should be something located at https://www.drupal.org/docs/8/core/modules for all core modules, but how much is unclear for content that is already organized by task. I think A and B in the summary is quick to fix if we don't start the discussion again and just let people use common sense. I just wanted check before I dived in ;-)

I don't mind being a section maintainer. Before the migration I think I could do almost everything with my docs team role ...

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

In the migrated system, we are not organizing by task any more at all. The contrib projects (modules/themes) will all have their own Guide areas, with a link automatically appearing on the project page when these are created for each major version. The core modules will be under docs/8/core/modules.

So I think if someone wants to make a Guide about "How to accomplish task A", which uses some core and some contrib modules, or compares several options, they would make that separately, and they could link to the documentation of how to use each core/contrib module they reference.

But the gigantic "Structure Guide" we had in the old documentation system, where both core and contrib modules were located under, for instance, a Forum section, is gone. It was not really maintainable and no one knew how to navigate it anyway...

DSquaredB’s picture

DSquaredB CreditAttribution: DSquaredB as a volunteer and at DSquaredB Consulting, LLC commented
Issue summary: View changes
DSquaredB’s picture

DSquaredB CreditAttribution: DSquaredB as a volunteer and at DSquaredB Consulting, LLC commented
Issue summary: View changes
eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
CreditAttribution: eojthebrave at Drupalize.Me commented
Issue summary: View changes
jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Part of this plan is supposed to be that old URL aliases should be turned into redirects when content is migrated. But this is not always happening... see #2874238: Broken links in various topics, where we found out that Block module pages that used to exist are now 404s.

Something is being missed in this migration...

eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
CreditAttribution: eojthebrave at Drupalize.Me commented

Just a heads up, I think the link used in #2874238: Broken links in various topics was actually a typo in the first place, and thus the appearance of a missing redirect here.

In that issue the bad link is http://drupal.org/documentation/modules/blocks, however the appropriate link is/was http://drupal.org/documentation/modules/block which does redirect. Note the s at the end of blocks in the first one.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Ah, right! Thanks for that correction. I am still not sure all the moved documentation has been redirected, but you are correct that this case isn't a problem. If I find more, I'll add notes here... maybe the other 404s I have been seeing lately are not core modules though.

eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
CreditAttribution: eojthebrave at Drupalize.Me commented
Issue summary: View changes

Taking care of items in "C" in the issue summary.

- I redirected https://www.drupal.org/docs/8/api/entity-api/entities-drupal-8-pre-delete to https://www.drupal.org/docs/8/api/entity-api as it was just a stub page that said, "Should contain information about the core entity API."
- Entity reference is no longer it's own module but instead just built into the core entity/field system
- Translation entity module was renamed to content translation #2024867: Rename translation_entity to content_translation. I created a page for the Content Translation module here https://www.drupal.org/docs/8/core/modules/content-translation
- Layout is new in D8 and there was no old page to migrate or redirect

eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
CreditAttribution: eojthebrave at Drupalize.Me commented
Issue summary: View changes

Everything under section "B" in the issue summary should be resolved now:

eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
CreditAttribution: eojthebrave at Drupalize.Me commented
Issue summary: View changes
David_Rothstein’s picture

David_Rothstein CreditAttribution: David_Rothstein as a volunteer commented

While the old urls "d.o/documentation/modules/dblog" will continue to work as redirects, they can only redirect to a single document so either D7 or D8. Which means that links from one of the versions of Core will go to the wrong version of documentation.
....
Ensure all old urls e.g. "d.o/documentation/modules/dblog" redirect to D8 version of the documentation. Even if a module is not in Core any more, still redirect to the 8 URL (which will be in the contrib section)

These redirects were added, but did anyone file the patches to fix the links in core beforehand? I couldn't find an issue/patch for this (except #2855175: [META] Many documentation / handbook URLs redirect to D7 content which was filed later for Drupal 8), but maybe I missed it...

For Drupal 7, the fact that the per-module redirects wound up pointing to the Drupal 8 version means we now have a lot of per-module help text links in Drupal 7 core which point to the Drupal 8 version of the page. (#2857606: Bad documentation link in admin/config/media/file-system is one example of that which brought the problem to my attention, but it's really just the tip of the iceberg.)

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

It doesn't look like anyone bothered to file issues to fix D7. If they had, probably they would have updated the issue summary and put a link there. Instead it says, under Next Steps:

5. Update urls in Drupal 7 core to link to appropriate doc guides e.g. drupal.org/docs/7/core/modules/[short-name]
Status: Blocked on A and B below.

I have no idea why someone decided it was OK to break all the URLs while we wait for the last couple of modules to have new URLs...