[Meta] Migrate documentation into the new system

The old user contributed documentation was a Wiki and it was very simple to correct or add missing documentation.

I've looked at the new documentation pages that are being rolled out, and it looks like this is no longer the case. Instead, each page is assigned a "maintainer" and there is a button to "discuss".

If this how you plan things to stay, I fear that this will not be sustainable. Some pages are bound to become abandoned as maintainers lose interest or just move on.

When this happens to projects, there is both a temporary fix (patches posted to the project's issue queue), and a procedure for repairing the situation.

If the user contributed documentation is no longer going to be a Wiki, how are you going to deal with abandoned documentation pages?

As a part of #2533684: Create 'Documentation' Section we are getting ready to migrate existing documentation into the new section.

It also looks like you're removing the old user created documentation pages.

There is two problems with this approach:

1. The documentation pages was very much interlinked. As you remove pages, these links go stale.
2. The Wiki pages was copyedited by a multiple of individual users over time, and information was added to have specific information in place to cater for the needs for miscellaneouscommunity activities (e.g. Project Applications and LWG to name just two such activities I know about). The individual maintainers that now is in charge of the new pages cannot possibly know about all these activities and what they require from the documentation, and will probably delete a lot of important information in the process because they do not understand its relevance or significance.

By all means - create all the new pages you want to create, but please stop removing the old pages until you understand what they're used for and from where they are linked to.

Is there an issue for migrating the contrib modules documentation?

I am very concerned about the migration discarding book hierarchy data. There are many modules where this is a vital part of the content, and losing it will mean a lot of manual work to restore it. Eg Feeds https://www.drupal.org/node/622696, and Flag https://www.drupal.org/documentation/modules/flag, to pick just two modules at random.

Having so big fonts require to make width to be wider

It's really hard to read https://www.drupal.org/docs/8/modules/features

> Regarding the hierarchy, flat hierarchy does not mean that all of the pages about a module will be in a single guide. We will create sub-guides to preserve hierarchy whenever makes sense. E.g. in the Feeds example there can be an overall Feeds documentation guide, with sub-guides: The site builder's guide to Feeds, The developer's guide to Feeds, Contributed plugin modules for Feeds.

Have you had a look at the Flag documentation? That nests quite deep. I'm really not happy about the prospect of that structure being lost.

Is there an issue where the contrib module docs migration is being worked out?

Is there an issue where the contrib module docs migration is being worked out?

I have the same question.

oopss... I should have read everything.

Thank you

Please don't migrate docs for Flag until the matter of what to do with the deep hierarchy is resolved.

Installation guide is done

Hi. I just wandered over to the Drupal 8 install docs, thinking I would test it out today, and there's hardly anything there. What am I missing?

https://www.drupal.org/docs/8/install

Isn't the content written already? Why not just link to https://api.drupal.org/api/drupal/core%21INSTALL.txt/8.1.x rather than have a confusing, broken-looking documentation site?

Opened #2811365: Code blocks should be able to show lines with 80 characters and #2811359: WYSIWYG editor breaks code formatting.

The "comment" feature of the new documentation has a pretty brain-damaged text format.

• It appears to be a plain text format that doesn't convert line breaks to <p> markup.
• It renders safe HTML (such as <p> and <a ...>as plain text.
• It doesn't understand links.

For an example of the brain-damage, see my comment here.

I assume no links is to prevent spam, but we really need to be able to link to other docs pages, issues, and API pages.

I assume no links is to prevent spam

We have the "Confirmed" user role to prevent non-trusted users from abusing their account here (to post spam and other unappreciated junk). I assume that anyone with the "Confirmed" user role can (and should) be trusted with posting links?

Updating status. Installation guide is done. Admin and security guide is in progres

I wanted to link some clients in need of support to the "updating modules/themes" documentation but it's missing any information about the update manager:
https://www.drupal.org/documentation/modules/update
I don't want to make my clients bother with FTP and finding passwords etc. because Drupal has this great solution for updating non-interactively using the update manager, is there any reason it's excluded in the official docs or is it something we can add there?

link in old docs: https://www.drupal.org/documentation/modules/update

According to the summary at the top, the installation guide has been migrated. However, when I try to view the installation system requirements, it's basically empty. What version of SQLite is compatible with Drupal 8?

requirements redirected to https://www.drupal.org/docs/7/system-requirements/overview
>SQLite 3.7.11 or higher

Notice to drupal.org documentation creators

Do not link to any of the new Documentation pages, using the textual 'friendly URL' in the address-bar. That URL will change every time someone decides to change the page's 'title'.

If you want to link to one of the new drupal.org documentation pages, login to drupal.org, (or register, and confirm your registration in your eMail), click the "Edit" button for the page you want to link to.

Remove the "/edit" portion of the URL that you will then see in your browser's address-bar for that page.

The permanent URL that you must now use to link to any new drupal.org documentation page will be similar to https://www.drupal.org/node/###### with numerals instead of '######'.

---

"Though a bit ranty," admittedly, that issue is here [2824170]

Drupal 8 media team has been maintaining "D8 media guide" on GitHub: https://github.com/drupal-media/d8-guide. The reason for that is the fact that having docs in some common format (Markdown in our case, but not limited to that) makes it easily portable and re-usable. Having it in a git repo is also beneficial since you have it versioned, one can easily clone and compile it in full locally, we get to use same contribution workflows as we're used to in our every-day life, ...

But there are also downsides (like always:)). Having it on GitHub/GitBooks and not on drupal.org causes big discover-ability problem, which we would like to solve. However, we wouldn't like to move away from current format.

I noticed that D8 user guide uses AsciiDoc. Would it be possible to do something similar for Media guide? Are there any APIs that would allow us to compile and publish changes to it automatically?

The compiled user guide still has some rough edges and does take some time for us to update. For example, #2831856: Deploy changes to User Guide modules etc.. The planned editorial process there is to update on Drupal.org when a tag is pushed. It hasn’t been fully automated yet. I wouldn’t want to add more guides like this.

If the Media guide fits into a chapter of the existing user guide project, that would work nicely.

Guess this may be the wrong place to discuss. But I used the documentation now from a newbee perspective to start learning codeing for Drupal By using this as a visitor of Drupal org I find it somewhat confusing that the documentation mixes d7 and d8 in the navigation trainl An example is:

https://www.drupal.org/docs/8/creating-custom-modules/naming-and-placing...

There is a link to https://drupal.org/node/1056468

So if you follow this

After changing the page the navigation trail on the right is changing and you see some d7 related things as well. I know that Drupal's docs must be extremely massive but this is a confusing behavior. Where is the place to suggest a better navigation trail? Is there any none else seeing my point or is this just a silly newbie opinion?

Don't know where to put this issue, but there's a problem with code block formatting on this page https://www.drupal.org/docs/7/api/render-arrays/render-arrays-overview#c...

I fixed up the markup there (using CKEditor) and added a note about this to #2741227-30: Enable CKEditor for more content types.

I am reporting this documentation page: https://www.drupal.org/drupalorg/style-guide/grid .

(I am not allowed to edit the page, and there is no "discuss" tab or "report errors" link.)

The page refers to a "design grid" with no context and explanation about how this "design grid" is part of Drupal. Two support questions and one bug report:

1. Where is the css that implements the "container-x" and "grid-y" classes used in the examples?"
2. Where am I supposed to put this markup?
3. The HTML-syntax is wong (no end angle bracket in some mark-up, and the end </div> for the container looks like it is the wrong place) and is not even obvious to me how to fix it.

This is the landing page arrived at after googling "drupal using 12 column grid". We need make sure doc pages are self-contained because every doc page is a landing page for Google. In this case, navigating up or sideways did not help me finding out how to use a 12 column grid when theming a Drupal site.

Just wanted to note that the PHP requirements for D8 can't yet be found in the /8/ section, and are only found in the docs for D7.

tvn wrote:

@gisle This issue is about migrating documentation into the new system. Please open separate issues in the Documentation queue for other questions/reports.

And pages in the new documentation system are broken. AFAIK, there are no such problems with the pages in the existing document system. I think you should have some sort of QA after a page has been migrated, rather then having them reported one by one.

As noted in #44 I am not allowed to edit the page, and there is no "discuss" tab or "report errors" link.

That is because the page you are talking about is not a documentation.

Well, it sure looks like documentation to me (it even uses the same distinctive Ubuntu Google font and the same layout as the rest of the Drupal.org documentation - and unlike the sans-serif font stack with Verdana, etc. that is used on the parts of Drupal.org that are not documentation. (I don't think I am the only designer that uses visual clues like fonts to classify content.)

But from your kind comment, I now understand that this page really is something different™. And also that it is the the user's responsibility to know the difference.

If you want to suggest improvements to the style guide …

No, I don't - not any more.

Reporting documentation issues at Drupal.org apparently requires one to understand how the cabal that manages documentation has divided the site up in twisty little documentation sub-sites, all different. This is a game I don't have the time to play.

The issue summary says:

Information for contributed project maintainers

If documentation for your project exists somewhere in Site Building Guide or any other documentation book, we will create a new documentation guide, and migrate existing docs into it. If you are project maintainer, you will be added as a guide maintainer, so that you could modify guide, its menu, its contents, add other guide maintainers, etc.

Please be prepared to spend a bit of time in the next few weeks modifying your documentation post-migration. If there is specific time before/after which you want us to migrate documentation for your project, please let us know in the comments.

Please clarify, you have NOT migrated my documentation (Ubercart), and if I try to migrate the documentation myself using the link (https://www.drupal.org/migrate/documentation/159733) on my bookpage (https://www.drupal.org/documentation/modules/ubercart), I receive an error message:

Migration cancelled. You tried to migrate over 30 child nodes. Usually a guide consists of a smaller number of pages. To prevent possible mistakes, please select a smaller sub-set of book pages for migration at a time.

There is NO information or documentation about how to "select a smaller sub-set of book pages for migration" - there is only the link on my main book page that says to click and the migration will happen.

Ubercart is a major module that has been around for 10 years. It has tens of thousands of users and hundreds of book pages of documentation at https://www.drupal.org/documentation/modules/ubercart. This whole migration business seems to be focused on minor, small projects and has really ignored the needs of maintainers like me who support tens of thousands of users and several dozen projects.

It would have been really nice if you could have informed project maintainers like me when you changed the documentation system, and it would have been even nicer if you had migrated my documentation yourself after making this change - leaving it to me to discover some months later and try to migrate it myself is a little anti-social. Throwing an error because I have too much documentation is just ridiculous.

TR - you can migrate smaller batches of pages by starting at a point deeper in the book hierarchy, such as https://www.drupal.org/node/1312862.

The new documentation pages have some structural differences which don’t automate well. Such as the summary field - the migration tries picking out the first few words, but there’s a good chance that’s not a great summary. Each page should get some review by a person as it is migrated, unfortunately that does add up for more-documented projects.

Naikalongus,
here are some hints about how do use the issue queue:

• If a task is already assigned, it should only be reassigned by one of the project managers for Documentation ore the person it was assigned to. (This task was already assigned tvn).
• Even if a task is unassigned (this one was not), do not assign it to yourself unless you actually plan to carry out the task yourself.
• Do not change the category of an existing task unless you know what you are doing.

To me it looks like you tried to indicate that you need some sort of support regarding Documentation. If that is the case, open up a new issue in the Documentation project. Explain clearly why you are creating the issue and what you request.

zumznm - please do not post test content.

Reverted to a previous version.

Change "less" to "fewer." Also changed "but" to a comma - but not sure that's an improvement after all.

I unassigned the issue, since tvn is no longer active here.

Hm, most of the general documentation is migrated now and this issue has stalled.

Should we close this issue and create a separate issue for contributed modules? Many maintainers have not migrated their pages yet. Maybe because they didn't write the current book page? (The maintainer might focus on the project page.)

Very little feedback on my comment from 1st of August ;-)

If we create a separate issue for contrib modules we could make a task list (in the issue summary) based on the list of modules on https://www.drupal.org/documentation/modules/contributions I think that could help, but most likely we just don't have the resources to get the job done.

hansfn wrote:

Should we close this issue and create a separate issue for contributed modules?

+1 from me.

If we create a separate issue for contrib modules we could make a task list (in the issue summary) based on the list of modules on https://www.drupal.org/documentation/modules/contributions I think that could help,

There is a problem with that list. About 9 months ago i migrated all the documentation for the modules I'm the maintainer for. Almost none of it appears in that list.

On most of them, there is a box on the top saying:

This guide has not yet been reviewed by Contributed modules maintainer(s) and added to the menu.

Example: https://www.drupal.org/docs/7/modules/advanced-help

I'm not sure how this review process is supposed to work, but I don't think it is working now.

I'm not sure how this review process is supposed to work, but I don't think it is working now.

The review process doesn't working because the guide maintainers, eojthebrave and me in this case, aren't notified in anyway that there are guides that need review. I have complained about this to drumm in some issue earlier. Even if we actively look for guides that need review, it's "impossible" to find them because the (group) content list only provides a "published" filter, not a "reviewed" filter. If you have time / energy, please create an issue for this.

PS! I'm happy to "review" your modules guides today - just sent the list directly to me.

hansfn wrote:

If you have time / energy, please create an issue for this.

I've created a child issue in issue queue for Drupal.org customizations, see: #3017611: Migrated documentation for contributed projects does not show up in the new list of documentation.

I’ve opened migration for the remaining books and added links to the issue summary:

• Site Building Guide
• TO BE MIGRATED
• Migration archive
• Reference
• Tutorials and site recipes

Migrating or deleting book pages directly helps the Drupal.org migration past Drupal 7. The book module and content type will not be on the site in the future.

Now-useless pages can and should be deleted. I think https://www.drupal.org/migration-archive might have been the place to collect pages to be deleted.

(fixing link)

@drumm, thanks for making a new list.

I have skimmed through all those except "Migration archive" and did not find anything that I thought need to be moved to the new documentation system. I think this is also supported by no one else has come along and moved pages either.

Because you said that "Migration archive" was probably for items to delete I tried to move "Reference" there. Instead I get get this error, "You tried to migrate over 30 child nodes. Usually a guide consists of a smaller number of pages. To prevent possible mistakes, please select a smaller sub-set of book pages for migration at a time." I tried 3 more times with smaller sections but kept getting the same message. So, it there some way to make it easier to move them?

I suppose that question applies to deleting the pages as well. Although, I must admit I don't feel that I have the knowledge to delete community history.

I have skimmed through all those except "Migration archive" and did not find anything that I thought need to be moved to the new documentation system. I think this is also supported by no one else has come along and moved pages either.

I think that is a too broad statement. Firstly, there is a lot of content under these guides. I skimmed too and found a lot that is useful, but needs updating. Secondly, people are finding the pages using search and are happy with that. The don't care which system the pages are in.

Anyway, we aren't interested in moving this mostly D7 stuff to the new system. We don't have the resource to do it properly. So either we delete or we make a static archive of the pages. (A minor clean-up before archiving is necessary.)

Thanks for looking at this. Some pages on the https://www.drupal.org/to-be-migrated list have been migrated, for example:

OLD
Disable Drupal (>=8.0) caching during development
https://www.drupal.org/node/2598914

NEW
Disabling and debugging caching
https://www.drupal.org/docs/develop/development-tools/disabling-and-debu...

Since the old page can now be deleted and removed from https://www.drupal.org/to-be-migrated, should we add a new "Page status" called "Migrated", or should I create an issue and request deletion of the old doc page? Or is there another method?

The reference book does look like it has a lot that can be deleted, and may have some hidden gems.

I'd like to go ahead and bulk delete:

• PHP block snippets https://www.drupal.org/node/21867
• PHP block visibility settings https://www.drupal.org/node/60317
• PHP page snippets https://www.drupal.org/node/23220

and their child pages. The PHP input format and block visibility are anti-patterns now.

I deleted https://www.drupal.org/node/2598914 and replaced with a redirect for the new page, thanks ressa.

We do need child issues like #2832228: Review and migrate 'To be migrated' book for batches of pages that are achievable. Each page can be:

• Migrated
• Deleted with no replacement
• Deleted and replaced with a redirect

@drumm, Deleting those sections makes sense to me.

Yes skimming is a broad statement. What I did was go through an overwhelming majority of the pages. I was relying on the title and the heading to be indicators. And I did not keep track of the tens of pages that I read more closely. I was focusing on finding pages that I thought were worth saving.

I skimmed too and found a lot that is useful, but needs updating.

If you list those pages then we can work on were to move them to.

Secondly, people are finding the pages using search and are happy with that

I have no evidence to support that. What I do know is that there are issues in the core queue for correcting links to any of the 'older' documentation.

I have made some issues as suggested.

It may make sense to take a different approach. Instead of a small group hunting for pages to keep it could be better to ask the community. Say, make an issue that section X will be deleted by some date. And invite people to provide links to the pages they find useful.

Checking which pages in the TO BE MIGRATED section are worth to migrate seems a time-consuming activity. There could be already documentation pages that cover the same topic, the covered topic is obsolete / not relevant anymore, or the information provided is not (anymore) correct.

Even with more people doing the task, it could take time to handle all those pages, or even to agree on what to do which every one of those pages.

I agree with apaderno - we should minimize the effort used to clean-up.

If quietone and ressa create issues with suggested deletions, I'm happy to review (and delete). Then we are only 3 people "wasting" our time.

It helps with "task" issues like https://www.drupal.org/project/documentation/issues/3441968

@drumm: Yes, go ahead and delete PHP block snippets, PHP block visibility settings, PHP page snippets

I skimmed too and found a lot that is useful, but needs updating.

@hansfn, What is your plan for these pages? Can you share the links?

My plan / wish is to remove as much as possible because we 1) don't have the resources to update them and / or 2) IMO we add too much non-Drupal specific docs. That doesn't mean that these pages aren't useful ...

In general, to repeat myself, the problem is what to do with D7 specific stuff. We have migrated a lot already that we maybe would deleted now.

These are now deleted:

• PHP block snippets https://www.drupal.org/node/21867
• PHP block visibility settings https://www.drupal.org/node/60317
• PHP page snippets https://www.drupal.org/node/23220

Code used was:

$page = node_load(23220);
$queue = book_menu_subtree_data($page->book);
$nids = [];
while ($item = array_shift($queue)) {                                                                                                                                                                         print $item['link']['nid'] . ' ' . $item['link']['title'] . PHP_EOL;
  $queue += $item['below'];
  $nids[] = $item['link']['nid'];
}
node_delete_multiple($nids);

So deleting more trees of pages is technically straightforward.

And agreed on this not being an ideal way to spend time, but this is what we need to do whenever there is a migration to something new. There is twice as much technical debt as long as there are 2 ways to do documentation. Unless we bulk delete everything or auto-migrate outdated/etc book pages to the current system, there's unfortunately no way around the sheer volume of docs that were a good idea at the time.

I get overwhelmed when I start looking at this. So much nice stuff contributed over the years, but auto-migrating it will probably just create a maintenance nightmare.

Anyway, @drumm could you delete all sections named something with D5 / D6 Migration archive? Maybe all of it is D5 / D6, but quicker to review when the obvious stuff is gone.

As I completed #3442307: Decide what to do with 'Tutorials and site recipes' I added 3 new capabilities:

• Removed the 30-book-page cap on bulk migrations. However, migrations via the UI still only migrate into child pages of a single guide. So this is actually only limited usefulness. https://git.drupalcode.org/project/drupalorg/-/commit/7a6290a27763e966fa...
• Added a drush command to flatten a tree of book pages into a single page. https://www.drupal.org/docs/7/howtos/book-drupal-7-the-essentials had many chapters with ~15-25 tiny child pages. This command recursively merges the child pages into the parent page, adding h2/h3/etc headings for the titles, moving attached files to the parent, and adding redirects to replace the deleted pages. https://git.drupalcode.org/project/drupalorg/-/commits/7.x-3.x?ref_type=...
• Drafted a process for migrating a book page to be a guide. After a couple og_menu-related issues, this looks like it is working well. However, on next edit, the character limit for the guide’s description will be enforced; that’s probably why we didn’t build this before. This can be adapted to move a tree of book pages with hierarchy if needed.

Anyway, @drumm could you delete all sections named something with D5 / D6 Migration archive? Maybe all of it is D5 / D6, but quicker to review when the obvious stuff is gone.

Done, and I’ve reviewed & completed the deletes requests in the child issues.

I looked more closely at the Migration archive tonight. It mostly for Drupal 5 and 6 with some Drupal 7 or 8 mentions, but all outdated. The exception could be the archive of past events. There might be community history there that is not anywhere else. For example this page lists the developers who were at the sprint in Antwerp 2005.

2008-03-03: DrupalCon Boston 2008 > Contributing to Drupal: A guide for everyone should allow to download slides, but all the given links return a 404 error.

Since there are child issue, adding meta to the title.

The links mentioned in #87 are for lullabot.com, so d.o never stored that data.

I meant that a page giving only three links which return a 404 error is not much helpful. It could be probably removed too.

Agreed the past events should be migrated.

I updated https://www.drupal.org/node/233045 to removed the dead links.

The migration tooling so far has been really geared toward discouraging huge hierarchies of pages, but this section does greatly benefit from hierarchy, and should be migrated with some of it. I may be able to do it with some manual work to get additional automation going. In the meantime:

• Should the year-level of pages, like https://www.drupal.org/node/299564 for 2006, be removed? So there is a simple list of all the events here.
• Should individual events, like https://www.drupal.org/forum/general/news-and-announcements/2006-08-07/2..., or Summer of Code years, like https://www.drupal.org/google-summer-of-code/2006 be merged into a single page, with headings for the sub-pages?
• Where would be a good place for these pages to land in a documentation guide?

Is there some way we could migrate the events to d.o - community/events/past-events The content itself is probably not that useful, but the fact the events took place is nice to preserve.

And maybe all the Google Summer of Code events could be removed - we have https://groups.drupal.org/google-summer-code

Is there some way we could migrate the events to d.o - community/events/past-events The content itself is probably not that useful, but the fact the events took place is nice to preserve.

Some of the old events looked like they would be a bit large to flatten into a single page, which would be required for moving into community events.

And maybe all the Google Summer of Code events could be removed - we have https://groups.drupal.org/google-summer-code

We also need to figure out the best way to handle groups.drupal.org, which could end up being a static archive. I wouldn't move anything there. That did lead me to find https://www.drupal.org/community/contributor-guide/reference-information..., where those pages could land.

Some of the old events looked like they would be a bit large to flatten into a single page, which would be required for moving into community events.

I was thinking just keeping the title - really. Looking at https://www.drupal.org/node/46559 (as an example) the sub pages doesn't have much value.

Yes, if History of Google Summer of Code was turned it a doc guide, you could just move the GSOC stuff there.

Found this issue about pages in the 'Migration Archive'. #1243274: Plan to archive DrupalCon/event and GSOC/GCI content from drupal.org. I haven't read it in depth and am adding this comment as a reminder to do so.

Just updating the IS to strikeout the recent fixes.

I think the only remaining work here and in child issues is for me to automate bulk moving the remaining 5,806 book pages.

Of course, if there is any remaining that is outdated or duplicitous, and can be deleted, please call that out and that can be done.

I got together a quick script to migrate book hierarchies and have migrated:

• https://www.drupal.org/drupalorg/docs/archive-of-past-events
• https://www.drupal.org/community/contributor-guide/reference-information...

$page = node_load(33887);
$destination_guide = node_load(28580);
$test_mode = TRUE;
//$test_mode = FALSE;

if ($destination_guide->type !== 'guide') {
  print 'Not a guide!';
  return;
}

$queue = book_menu_subtree_data($page->book);
$nids = [];
$mlid_nid = [];
while ($item = array_shift($queue)) {
  if (empty($mlid_nid)) {
    $mlid_nid[$item['link']['plid']] = $destination_guide->nid;
  }
  $mlid_nid[$item['link']['mlid']] = $item['link']['nid'];
  $queue += $item['below'];
  $nids[$item['link']['nid']] = [
    'parent' => $mlid_nid[$item['link']['plid']],
    'type' => empty($item['below']) ? 'documentation' : 'guide',
  ];
}

foreach (node_load_multiple(array_keys($nids)) as $node) {
  print $node->title . ' (' . $node->nid . ') → ' . $nids[$node->nid]['parent'] . PHP_EOL;
  if ($node->type !== 'book') {
    print 'SKIPPING ' . $node->type . PHP_EOL;
    // TODO if this was to be a guide, bad things will happen!
    continue;
  }

  $node->type = $nids[$node->nid]['type'];
  $node->language = 'en';

  // Remove the page from book schema.
  if (!$test_mode) {
    book_node_delete($node);
  }
  $node->book = [];

  $node->menu = [
    'link_title' => $node->title,
    'menu_name' => 'menu-og-' . $nids[$node->nid]['parent'],
    'parent' => 'menu-og-' . $nids[$node->nid]['parent'] . ':0',
    'plid' => 0,
    'enabled' => 1,
  ];

  // Do not create alias during intermediate save.
  $node->path = ['pathauto' => FALSE];

  // Create a revision for the migration.
  $node->revision = TRUE;
  $node->log = t('Migrating to new documentation system.');

  $node_wrapper = entity_metadata_wrapper('node', $node);

  // Summary is a new field for documentation. Lets auto-fill it
  $node_wrapper->field_summary->set(truncate_utf8(strip_tags($node->body[LANGUAGE_NONE][0]['value']), 140, TRUE, FALSE));
  if (!$test_mode) {
    $node_wrapper->save();
  }

  // Use normal path aliasing.
  $node->path = ['pathauto' => TRUE];

  // Do not create a revision for the second save.
  $node->revision = FALSE;

  // Empty out summary attached to body field.
  $node->body[LANGUAGE_NONE][0]['summary'] = '';
  // Open comments.
  $node->comment = COMMENT_NODE_OPEN;

  // Set the group reference for the node. After the initial save so field
  // changes have kicked in.
  $node_wrapper->og_group_ref_documentation->set(intval($nids[$node->nid]['parent']));
  if ($node->type === 'guide') {
    $node_wrapper->{OG_GROUP_FIELD}->set(TRUE);
    $node->og_menu = TRUE;
    $node_wrapper->field_new_page_and_guide_review->set(1);
  }
  if (!$test_mode) {
    $node_wrapper->save();
  }
}

Now that all books have been triaged in child issues, we are left with 123 orphaned book pages. There’s some gems like https://www.drupal.org/teapot that should have a place to land, and others that can be deleted.

@drumm, can you supply the list of links?

The orphaned pages are now at https://www.drupal.org/node/3522465

I took a first pass through deleting placeholders, obvious D6 & earlier, and a couple terrible security ideas. 101 pages remain

Deleted the docs for unsupported project

• Ember style guide
• Web Engagement Management
• Usage of the Default user picture styles module
• How to use the Faceted Search
• Moneybird Commerce
• Profile Location Configuration and Customization
• Views Book Documentation

Edit: and one at the end

Created an issue in these projects, that have a D8 stable release, to migrate the docs.

Forward module - #3522627: Migrate module documentation from old book style
GA Push #3523786: Migrate documentation from old book-style
Module - Visual Website Optimizer #3523831: Migrate module documentation from old book style
Single Page Apps /#3523830: Add documentation page to the contributed module guide
Term Merge #3523829: Migrate module documentation from old book style

@drumm, The can be deleted but I don't have edit accees, the bitcahce project is unsupported.

https://www.drupal.org/docs/extending-drupal/contributed-modules/contrib...
https://www.drupal.org/docs/extending-drupal/contributed-modules/contrib...

@drumm, I deleted the pages for "unsupported modules and modules only compatible with Drupal 6 or earlier" for the list of orphaned list here and the Contributed module documentation archive.

What about the pages for modules that do not have a stable D7 release?

I deleted a couple pages that had docs on how to use jQuery which are readily available elsewhere on the internet, and some pages related to the obsolete Dreditor browser extension.

• Get Radio button value through jQuery
• Get Select box value through jQuery
• Filing a followup
• My program to count $R(x)$ and $\breve R(x)$
• Prefix Suffix Title -- this was 3 sentences of text related to a non-existent module and a couple comments saying this module doesn't exist
• Setting up a local test site to work on Git related patches for d.o -- content related to setting up Git to create patches for Drupal 6, no longer relevant and the updated version of this exists in the contributor guide.
• facebook rss... -- the page content was a note that said "In case you are wondering this is impossible ..." 🤷
• hirji time conversion in drupal -- some example PHP code for doing date conversions that is covered elsewhere on the internet and not specific to Drupal.
• style don't create the resource when clean URL is enabled with Nginx like inverse proxy --- this page contained a question about nginx that should have probably been a forum post, and had no answers or additional comments.

I did a quick pass through the orphaned book pages (https://www.drupal.org/node/3522465) and deleted a couple of pages for themes that didn’t have D7 or later versions.

The can be deleted but I don't have edit accees, the bitcahce project is unsupported.

And those have been deleted too, thanks!

What about the pages for modules that do not have a stable D7 release?

I think we have to keep those for now, there will be plenty of people with D7 sites that they need to figure out, and documentation has potential to help.

It's really great with all the clean up, though many Drupal 7 doc pages indexed in search engines now give a 404, since they have been deleted, without having a redirect to a replacement page, probably because there wasn't one.

This is unfortunate, since these pages may both be linked to from other pages on the internet, or on drupal.org, and the topics are still themselves relevant in Drupal 11, 12 etc. so people will still be looking for the info.

It's Drupal 7 pages like these:

https://www.drupal.org/node/1995428
Step 4 - Rename default.settings.php to settings.php
Install Drupal 7 in one-minute (or Drupal 6) Using Webhost Control Panel ... Step 4 - Rename default.settings.php to settings.php · Step 5 - Putting WAMP ...

https://www.drupal.org/node/2608620
Increase Maximum File Size
11 Jul 2017 — Although many other PHP settings are configurable by using ini_set() in the settings. ... Administer user profiles in Drupal 7 · Administering ...

As I see it, there are two options:

1. Handcraft precise redirects

   Either add a redirect to the corresponding page, if it exists, or a fitting section or page on drupal.org. This is labour intensive, and may not be realistic. Though, it could be considered for the top 50 of 404'ing Drupal 7 documentation pages?

2. Do an automatic search

   If a node is not present on drupal.org -- if possible, do a look up to somehow get the title of the deleted node, and do a search like https://www.drupal.org/search/site/Increase%20Maximum%20File%20Size?f%5B..., perhaps with a text like "Sorry, this page is gone, but we did a search, maybe it can help?"

We can continue putting redirects in by hand. Where should the two pages you linked go to?

We do keep records of deleted nodes, but now is not a good time to engineer new functionality as we’re migrating the site. That is something we could build once documentation is fully migrated, if the search for the previous page title is tested and shown to be useful.

If I recall Correctly, The page "Install Drupal 7 in one-minute (or Drupal 6) Using Webhost Control Panel", was Written by me , and I had wanted it deleted anyway. because it was completely outdated. My Opinion, get rid of it. thank you. I would have deleted it myself, years ago, but I did not have that level of authority.

The page "Increase Maximum File Size", If I remember correctly, Was a huge mass of mostly irrelevant comments, But which terminated with a detailed explanation of mine, on how to ' Definitively' achieve an increase of file size, Keystroke by keystroke, mouse click by mouse click.. Addressing new bees common mistake of saving INI files. as Ini.txt file in windows. and other similar newbie errors, related simply to day-one-drupal-users lack of experience.

Aside from my detailed guide, which was actually in 2-parts, but I forget The differentiation between my two parts, and why I was compelled to have 2-parts... Anyway,If I were you, I would let that page fade away into history. If you were to look at it, you might recognize what I am talking about, and you might pull my new-b information out into a brand new how-to guide, but aside from that, please send it to oblivion.

"All the best; intended." ~ Grandpa Chris ..An ongoing Drupal 7 reliant individual : o )

Thanks for a fast reply @drumm. I have experienced a fair number of drupal.org 404's recently, after doing a search for Drupal stuff in the search engines lately, and my best guess was that a bulk deletion had been done, without redirect. When this issue appeared in my dashboard, I was reminded of it.

So those two pages are just examples I quickly looked up, to use as examples as dead links, and I don't have an opinion on a redirect, sorry.

Until the new Drupal is launched (and possibly automated search on title?) we could have a "404 Not found documentation pages" issue, where we continually add 404's, and then set up redirects?

Thanks for sharing @christopher james francis rodgers :)

Though in this case, the question is not so much about resurrecting pages, but making sure that users are redirected to a page or section about the topic. So a user may not be looking for a one-minute set up, but info about "default.settings.php" and "settings.php" and find that link in the search engine. But it's a dead end on drupal.org. So we could instead redirect them to something that resembles that subject the most.

For the second example I used, it could be redirected to https://www.drupal.org/docs/8/core/modules/file/overview.

Another thing: It might be worth considering adding a "This is archived/old content" banner or something, like the warnings that api.drupal.org just got, making it clearer that some of these are old or archived documentation pages. It could be added automatically at the top of all pages under certain paths? See for example, a page like this:

https://www.drupal.org/docs/extending-drupal/contributed-modules/contributed-module-archive/contrib-modules-for-building-the-site-functionality/dates-and-events/datecalendar/drupal-6-datecalendar/date-locale-time-zone

https://www.drupal.org/docs/extending-drupal/contributed-modules/contrib...

It says:

Date Locale & Time Zone settings

Last updated on 30 April 2025
[...]

... so a user may easily miss that this doc page is for an older version. A rule could be, that since it's under https://www.drupal.org/docs/extending-drupal/contributed-modules/contributed-module-archive a message like this could be shown at the top of the page?

We have a notice like that for D7 documentation already. For example: https://www.drupal.org/docs/7/understanding-drupal

https://www.drupal.org/docs/extending-drupal/contributed-modules/contrib... is more of a lost & found of potentially-unmaintained documentation that could still use triage. For example, https://www.drupal.org/docs/extending-drupal/contributed-modules/contrib... has a supported version compatible with Drupal 11, and that documentation has a good chance of being relatively current.

The only thing needed to close out this issue is triaging the orphaned book pages at https://www.drupal.org/node/3522465

Ah yes, and that works well, alerting users that this is for an old version, Drupal 7.

Could we get a similar banner for pages under https://www.drupal.org/docs/extending-drupal/contributed-modules/contributed-module-archive/ as well?

The reason I raised this issue, is because users are finding these Drupal 6/7 doc pages, and they look relevant and updated ...
https://www.drupal.org/forum/support/post-installation/2025-06-07/time-z...

I migration Webform Default Fields to the wrong parent guide. I don't have an option to move it to where is should be, https://www.drupal.org/docs/7/modules/webform-default-fields.

Can someone fix this?

Tried to fix it now.

@hansfn, thanks!

I have done all I can on the orphaned pages. I've migrated lots of module and theme pages and deleted some that had replacements or the content was on the project page. I have looked at the remaining pages and nothing stands out that should be kept except for the 'teapot' image. Unfortunately, I don't have a recommendation of where that should go.

Oh, I should also mention that I don't know what to do List of Drupal.org former image nodes. What is the plan for all those images?

@drumm I created #3531293: Add "This is archived/old content" banner for old documentation pages.

I asked in committer slack about the teapot image. Gábor Hojtsy said it was from DrupalCon New Orleans, and taken from this image. He looked at the revision log and thought it was an insider joke at one point and he didn't expect it was used for anything. Hope that helps!

Thanks everyone!

I pushed through the remaining book pages and we’re officially done.

• The old images live on at https://www.drupal.org/drupalorg/docs/drupalorg-archives
• I deleted many vague/incomplete pages
• And migrated the rest to D7 module documentation