Migrate documentation into the new system

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

• Site Building Guide →
• TO BE MIGRATED →
• Reference →
• 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.