Review and migrate "Site Building Guide" book

@drumm, could you mass delete Zen for Drupal 5 and 6 → . Several of the other "big" themes like Fusion and Omega still use these guides and should be migrated - if we still care about D7 ...

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.

Yes, you lack permission. I don't, but got

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.

In addition OG was missing a D7 guide to migrate to, but I have created that now → and added you as maintainer. You should be able to migrate (in multiple steps). Or maybe delete the D6 stuff first gets you under the 30 child node limit.

quietone is not one of the maintainers for 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, 📌 Add link to module documentation on project page Active . 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?

Reading your experience with migrating the Organic Groups documentation, I remember that I had the same experience long time ago (when we started migrating stuff). It is too much work for us to handle. I suggest:

1. For guides that cover modules with D7 release, we create a critical issue (in the corresponding project issue queue) saying something like:
   1. To preserve existing module documentation in the the old site building guide, you (the maintainer) have to migrate the content within [a date or a duration]. If the documentation isn't migrated withing the deadline, it will be deleted to enable migrating drupal.org off D7.
   2. Then in the issue description, tips for migration could be inserted - like creating the D7 docs guide first, so you have some where to migrate the content. It makes sense that the maintainer creates the new doc guide, so the ownership is correct.
   3. Finally, we could ask for an update of the documentation URL on the project page. (To get a name instead of an URL displayed, you need to select a doc guide from the new system.)
2. For guides that cover modules without a D7 release, we mass delete - please, drumm

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!

Some suggested changes to the "How to migrate documentation" list:

1. First, visit the appropriate new home for the documentation, and create a new documentation guide for your project (if it doesn't exist).
2. Secondly, 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 the pages.
4. Finally, after the pages are migrated, edit the project page. Scroll to the bottom, select Resources and add the link and text for the migrated documentation.

Open questions:

• How do we track which documentation in the Site Building Guide that we have created issues for? Google Docs spreadsheet?
• Should we in the issues we create, link to the documentation to be migrated? That removes the "find" step in the list above.
• Since most of this documentation is for D7, should the links after " For modules the new home is" be to the D7 docs? For example https://www.drupal.org/docs/7/modules →
• Deadline?

I think I will answer yes to the first three. I guess Drumm should set the deadline, but if not - 1st of October?

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 📌 Migrate documentation into the new system Active . 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 📌 Contrtib Themes to be deleted from the Site Building Guide before migration Active

@drumm

I have created a issue for deleting contrib module pages. https://www.drupal.org/project/documentation/issues/3504597#comment-1597... 📌 Contrtib Modules to be deleted from the Site Building Guide before migration Active

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 📌 Site Building Guide - more pages to be deleted Active

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.