Review and migrate 'Site Building Guide' book

Just adding the top level pages.

I came across Organic Groups. So I looked that the Organic group project page and there is a link there, http://drupal.org/node/1114858, with no text. And that links directs to a href="https://www.drupal.org/node/1114858">Organic Groups in this Site Building Guide. So, I thought I would migrate it to the Organics Group project. However, I am faced with this

This documentation needs to be migrated into the new documentation system. If you are a project maintainer, create a new documentation guide for your project first and then migrate this documentation.

Which, if I understand correctly, then I do not have the permissions needed to migrate the docs.

quietone is not one of the maintainers for the Contributed module documentation documentation guide; that is the reason for the lack of permissions. (I apologize: I was just curious of how permissions on documentation work.)

@hansfn, thanks. Even the latest D7 documentation is over 30 nodes. :-(

I did start on migrating 'Organic Groups' and got this message

Hierarchy will not be saved! All child pages will be on the same level with the parent page in relation to the documentation guide.

So, this will take more work than I expected. It seems like I should do 1) migrate a set of pages, say Setup 2) Create a Guide, 'Setup', in OG 3) Move all the pages just migrated to the new guide. And then repeat that for each part of the OG documentation.

I migrated the Organic Groups documentation for the latest D7 version to the new system. This is a good test case due to the size.

The problems I found are

1. Because the hierarchy is lost I had to create new Guides to keep the organization. Then when putting pages into the newly created guide, I would get an error about something not being in the guide. Sorry, I didn't save the error. That meant re-saving every page at least twice. 2) 15-30 seconds it takes for a page to load on edit.
2. For each top level page I had to created a guide. Since the top level page is also migrated, that meant that the top level page is now obsolete.
3. I can't delete the obsolete pages, so there is more work for someone else.
4. The link on the project page is still a URL instead of nice text. In this case, perhaps because that top level page still exists for the D6 and earlier D7 version docs.
5. This is the responsibility of the project maintainers and they should be involved.

What I am think now is that we should have an issue generated for each project to alert the maintainers that the docs are leaving. The issue should be Critical and an expected date of documentation deletion given. This is a related issue I made for the Tour module, #3445861: Add link to module documentation on project page. Not quite the same as it does involve migrating old documentation.

Find quite a few that have no releases for Drupal 7+. Can those be bulk deleted?

I agree with #12. I created a child issue for #12.2. And will work up some text for discussion for #12.1

How is this for an issue?

Issue title: Migrate documentation to new documentation system
Priority: Critical
Category: Task

This module, theme or distribution has documentation in the old Site Building Guide, which will not exist when Drupal.org is migrated off of Drupal 7. To preserve your existing documentation you (the maintainer) need to migrate the content to the new documentation system. For modules the new home is Contributed module documentation, for themes it is Contributed themes, and for distributions it is Drupal distributions

If the documentation is not migrated within the deadline, it will be deleted before Drupal.org is migrated off of Drupal 7.

If you have any questions, ask in #documentation or on the issue (some new issue for support)

How to migrate documentation

1. First, find the documentation for your module, theme or distribution. There may be a link to the documentation may be on the project page in the lower right. If not, search the Site Building Guide book for your module, theme or distribution.
2. Follow the instructions in the yellow section at the top of the page.
3. Edit the project page, scroll to the bottom, select Resources and update the link and text to the documentation.

Thank you!

I like those changes, I did remove the 'first, second and finally' because it is redundant in an ordered list. Then, for question 3, I added a sentence for the Drupal 7 documentation links. So, there are now links to both D7 and D8 and the maintainer can select the one(s) they need.

This module, theme or distribution has documentation in the old Site Building Guide, which will not exist when Drupal.org is migrated off of Drupal 7. To preserve your existing documentation you (the maintainer) need to migrate the content to the new documentation system. For Drupal 7, the new home for module documentation is Contributed module documentation, for themes it is Contributed themes, and for distributions it is Distributions. For Drupal 8+, the new home for module documentation is Contributed module documentation, for themes it is Contributed themes, and for distributions it is Drupal distributions

If the documentation is not migrated within the deadline, it will be deleted before Drupal.org is migrated off of Drupal 7.

If you have any questions, ask in #documentation or on the issue (some new issue for support)

1. Visit the appropriate new home for the documentation, and create a new documentation guide for your project (if it doesn't exist).
2. Find the old documentation for your module, theme or distribution. There may be a link to the documentation on the project page in the lower right. If not, search the Site Building Guide book for your module, theme or distribution.
3. Follow the instructions in the yellow section at the top of the documentation to migrate all the pages.
4. Edit the project page. Scroll to the bottom, select Resources and add the link and text for the migrated documentation.

Answer to questions
1. I would prefer a tag but if there are objections, than a google spreadsheet.
2. Sure, if if can be automated.
3. As above
4. I am not sure about the deadline. I have 3 months in my head because of working in Bug Smash. That would be from the date of the email too, which would be later that October 1. But that may be long enough for people to forget, so something shorter. Maybe there is some precedence we can use?

This is coming along nicely, :-)

For contributed modules, themes, and distributions - I think we just have to migrate everything as-is, potentially into a guide labeled “Archival” or similar. There isn’t a good machine-readable project ↔ documentation linking, so even tracking down each project to get the list of maintainers would be quite a task. And even then, I suspect maintainer response rates would be quite low.

Archival is fine by me.

Will this break the links that any module/theme/distribution is using?
What will happen to the book outline for the pages?

Should there be a blog post to inform maintainers of the move and consequences?

I completed the deletions from the issue summary, except for https://www.drupal.org/docs/7/modules/ultimate-cron. That is already migrated, and I don’t have an automated process for recursively deleting a documentation guide. There’s a decent chance I’d manually delete the 30 pages, even though that is a bit much to not automate.

Will this break the links that any module/theme/distribution is using?

In general, migrations and page merges have added redirects as they go.

What will happen to the book outline for the pages?

I’ve been working towards tooling that can migrate with hierarchy, some notes are at #2762837: [Meta] Migrate documentation into the new system. Many of the sections for single modules/themes might be flattened to one page first. For example, https://www.drupal.org/node/402796 could have its 2 child pages merged into itself.

Should there be a blog post to inform maintainers of the move and consequences?

We could probably use a general blog post highlighting the need for help triaging old book pages, and mentioning its progress toward upgrading Drupal.org.

@drumm @quietone, see my child issue for a list of theme pages we can delete. This list is for modules that are unsupported or only have D6 releases. https://www.drupal.org/project/documentation/issues/3504356

@drumm

I have created a issue for deleting contrib module pages. https://www.drupal.org/project/documentation/issues/3504597

I was not finding many pages to delete, so I am going to work on migrating the theme pages and creating module issues.

For module documentation, I can go ahead and bulk migrate the remaining documentation as-is. It still could use attention from project maintainers, but we don’t need to have everyone spend time on repetitive migrations. I may do the same for module & theme documentation.

And just parent pages to be deleted can be listed, I have automated deleting trees of book pages.

@drumm I added another ticket, and came up with lots more pages to delete.
https://www.drupal.org/project/documentation/issues/3505283

I've started migrating the Contributed Themes, and will be finished with that in the next week or two. I'll add issues to track that effort too.

@drumm

I have finished migrating ALL the Contributed Themes in the Site Building Guide! You can delete this and all subpages.
https://www.drupal.org/node/196218

You can review my work in these issues
#3505665: Migrate Contrib Themes from Site Building Guide to D7 Wiki - Part 1
#3505962: Migrate Contrib Themes from Site Building Guide to D7 Wiki - Part 2
#3506220: Migrate Contrib Themes from Site Building Guide to D7 Wiki - Part 3
#3507289: Migrate Contrib Themes from Site Building Guide to D7 Wiki - Part 4

wylbur - you should have seen a warning block at the top of book pages with

This documentation needs to be migrated into the new documentation system. If you are a project maintainer, create a new documentation guide for your project first and then migrate this documentation.

If you don't have that, let me know and I’ll double check access to that. Using the links in that block migrates the pages in-place, preserving authorship and revisions, and the old pages are moved, so no additional deletion is needed. This also removes the need to add any redirects or other affordances for URLs changing.

For the theme documentation, we’ll have to continue as-is, it isn’t worth the time to do additional cleanup. I’ll delete the book pages and resolve the issues.

Please do not migrate module documentation, except for special cases and identifying pages to delete. The migration process is cumbersome for more than a handful of pages, or anything with some hierarchy. I don’t want people spending time on busywork that should be automated. A special case might be something like - a module has new documentation and the book pages are being migrated into the module’s existing new documentation section.

Things to delete:

https://www.drupal.org/node/2008758 the last commit to https://www.drupal.org/project/vdd was seven years ago. It's dead, Jim.

https://www.drupal.org/node/417180 nothing here applies to modern Drupal.

@ghost of drupal past, thanks!

I have updated the IS with the info from #30.

Add item provided in Slack by chx.

I now have a script to migrate sections of book hierarchy. My process will be:

• Complete deletions and anything else pending in the issue summary.
• Starting from deeper in the book hierarchy, like https://www.drupal.org/node/779080, do any final cleanups and migrate. An example final cleanup for a small section would be flattening child page content into a single parent page, which I have also automated.

The pending deletions in the issue summary are now all done

Distribution documentation is now at https://www.drupal.org/docs/getting-started/drupal-distributions/distrib...

The comparison of modules is now at https://www.drupal.org/docs/7/extend/comparison-of-contributed-modules

The remaining module documentation is now at https://www.drupal.org/docs/extending-drupal/contributed-modules/contrib... where it can continue to be pruned, improved, moved, or left until the next major reorganization

Thanks everyone!

@drumm, thanks for all the help here. And for creating that archive with clear instructions for everyone.