Problem/Motivation

This is a follow up to #2776179: [meta] Add process plugin documentation to the codebase where process plugin documentation was copied from the handbook to the API documentation. To avoid maintaining the same content in two places (API and Handbook), the existing handbook pages need to be redirected to the API pages.

Discussion and conclusion on what to document where

See #31

The API Docs

  1. Are the definitive reference.
  2. Explain what the configuration keys do.
  3. Provides examples.

The Handbook pages

  1. Have a brief overview
  2. Have a link to the API documentation.
  3. Provides examples of various use cases.

In the next comment phenaproxima agreed with this approach stating

My feeling is that you can never have too many examples, in general -- it's not so much a question of which examples should go where, but how many examples can go where. The API docs should contain two examples at most -- maybe three for more complex process plugins -- and cover the most common use cases. The handbook pages, on the other hand, can have as many examples as we want to put there, covering any range of use cases, from the most basic to the most exotic

.

Proposed resolution

Update migrate process plugin documentation to not duplicate information in the API doc. This means removing that page and redirecting to the API page.

Remaining tasks

1. There are a couple of process plugins where the handbook documentation contains more information compared to the API documentation. These need to be evaluated with a decision either to discard the current handbook content or to copy the additional information to the API documentation. See child issues.

2. Request redirects from d.o. documentation infra team once all handbook pages have been merged to API.

User interface changes

N/A

API changes

N/A

Data model changes

N/A

Comments

quietone created an issue. See original summary.

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.0-alpha1 will be released the week of January 30, 2017, which means new developments and disruptive changes should now be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.0-alpha1 will be released the week of July 31, 2017, which means new developments and disruptive changes should now be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

quietone’s picture

quietone commented
Issue summary: View changes
Issue tags: +drupal.org documentation

tagging so we find this one. Updated the IS.

masipila’s picture

masipila commented

I had a quick look at this and at the moment the handbook pages are indeed duplicating the information found in the API doc.

I would not delete the whole process plugin guide but the individual process plugin pages can be redirected to the corresponding API doc pages.

1. I noticed that api.drupal.org seems to work so that if the version is not indicated in the URL, the latest released version is assumed (currently 8.4.x).

So we could create the redirects so that for example the current handbook page for default_value process plugin would be redirected to the corresponding API doc without specifying the version.

Any comments on this? This will be interesting when D9 will be released at some time in the future but I don't see that as a too big of an issue... I can't maintain the redirects myself even I'm the owner / maintainer of the guide. Setting the redirects needs always an request from the d.o. documentation infra team so we need to choose one target URL for one process plugin and stick with that.

2. I like the idea that we could add some additional examples to the handbook pages but I always like to think with concrete examples. So what kind of examples could we have in the handbook? In other words, any practical examples what the 'various use cases' mentioned in the issue summary could be?

I'm asking this to think about the structure of the handbook. The documentation system has two content types: Guides are collections of Pages. Currently the Migrate process plugins is a Guide. So a couple of concrete examples what could / should be added as examples would help to plan the structure of the handbook.

Markus

masipila’s picture

masipila commented
Parent issue: » #2561243: [meta] Migration system documentation
masipila’s picture

masipila commented
Title: Redirect handbook process plugin documentation to API docs » [Meta] Redirect handbook process plugin documentation to API docs
Issue summary: View changes

I went through all the process plugin documents in the handbook.

Most of them were 1:1 with the API documentation. In these cases I erased the handbook content with a note that the content has been moved to API documentation and hid the page from the handbook navigation. Here's a list of handbook pages where we had the same or more information in API compared to the handbook:
https://www.drupal.org/docs/8/api/migrate-api/migrate-process/process-pl...
https://www.drupal.org/docs/8/api/migrate-api/migrate-process/process-pl...
https://www.drupal.org/docs/8/api/migrate-api/migrate-process/process-pl...
https://www.drupal.org/docs/8/api/migrate-api/migrate-process/process-pl...
https://www.drupal.org/docs/8/api/migrate-api/migrate-process/process-pl...
https://www.drupal.org/docs/8/api/migrate-api/migrate-process/process-pl...
https://www.drupal.org/docs/8/api/migrate-api/migrate-process/process-pl...
https://www.drupal.org/docs/8/api/migrate-api/migrate-process/process-pl...
https://www.drupal.org/docs/8/api/migrate-api/migrate-process/process-pl...
https://www.drupal.org/docs/8/api/migrate-api/migrate-process/process-pl...
https://www.drupal.org/docs/8/api/migrate-api/migrate-process/process-pl...

The following process plugins have more information in the handbook compared to the API page so I did not erase the handbook page yet. I'll open child issues for each of these to discuss these. We have two options:

  • We include the additional info to API docs
  • We conclude that the additional info on the handbook is not needed and can be discarded.

These process plugins are:
https://www.drupal.org/docs/8/api/migrate-api/migrate-process-plugins/pr...
https://www.drupal.org/docs/8/api/migrate-api/migrate-process-plugins/pr...
https://www.drupal.org/docs/8/api/migrate-api/migrate-process/process-pl...
https://www.drupal.org/docs/8/api/migrate-api/migrate-process-plugins/pr...
https://www.drupal.org/docs/8/api/migrate-api/migrate-process-plugins/pr...

MenuLinkParent doesnot have a proper API documentation at all yet, pending #2845485: Refactor and document the MenuLinkParent process plugin

masipila’s picture

masipila commented

Child issues created for the remaining documentation merge tasks.

masipila’s picture

masipila commented
Status: Active » Postponed

Redirect request has been created to the Documentation Infrastructure team's issue queue: #2936508: Redirects from Migrate API handbook to API docs. Postponing this on that.

masipila’s picture

masipila commented
Title: [Meta] Redirect handbook process plugin documentation to API docs » Redirect handbook process plugin documentation to API docs

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.0-alpha1 will be released the week of January 17, 2018, which means new developments and disruptive changes should now be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

heddn’s picture

heddn
Primary language English
Location Illinois
commented
Status: Postponed » Active

This is no longer blocked.

masipila’s picture

masipila commented
Status: Active » Fixed

Redirects to api docs have been made.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.