Followup to #1697256: Create a UI for importing new configuration. The hook_help() text for the CMI synch operation could use some improvement and clarification, and the documentation page to which it links needs to be written.

Background: part of the task to update the hook_help texts of the modules for Drupal 8:
#1908570: [meta] Update or create hook_help() texts for D8 core modules

Also part of the larger task of making sure the config system has docs in general:
#2376749: [META] Update Configuration System Documentation

Tasks:
- review / write the hook_help text according to help guidelines
- review if the text in aggregator_help() is up to date for Drupal 8
- test the links embedded in the text
- update/review d.o. docs at http://drupal.org/documentation/modules/config

Files: 
CommentFileSizeAuthor
#41 1831798-39-update_hook_help.patch5.95 KBrajneeshb
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 94,594 pass(es).
[ View ]
#39 0001-Replacing-yml-for-YAML.patch5.11 KBdarol100
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 94,340 pass(es).
[ View ]
#37 1831798-interdiff.txt4.98 KBdarol100
#35 Screenshot from 2015-05-15 14:36:33.png101.4 KBdarol100
#34 0002-Made-Uses-headers-match-standard.patch5.2 KBrhuffstedtler
#28 update_hook_help_for-1831798-28.patch4.89 KBdarol100
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 92,252 pass(es).
[ View ]
#28 Configuration Manager Hook Help.png127.76 KBdarol100
#26 update_hook_help_for-1831798-26.patch4.52 KBpjonckiere
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 92,048 pass(es).
[ View ]
#13 node-2182101.txt1.59 KBbatigolix
#4 drupal-config-synchronizing-help-text-1831798-4.patch1.05 KBpaul.linney
PASSED: [[SimpleTest]]: [MySQL] 63,161 pass(es).
[ View ]

Comments

xjm’s picture

Component:views.module» documentation
xjm’s picture

batigolix’s picture

paul.linney’s picture

Assigned:Unassigned» paul.linney
Issue summary:View changes
Status:Active» Needs review
StatusFileSize
new1.05 KB
PASSED: [[SimpleTest]]: [MySQL] 63,161 pass(es).
[ View ]
  • Fixed the path for synchronize config help text
  • Added help text for synchronize page
  • Added link to documentation for synchronizing config https://drupal.org/node/2182101

Let me know if any omissions/errors.

regards,
Paul

mtift’s picture

@paul.linney: Thanks for the patch. Is there a reason why we need http://drupal.org/node/2182101 in addition to http://drupal.org/documentation/administer/config? It seems like the help text could just link to http://drupal.org/documentation/administer/config.

batigolix’s picture

Status:Needs review» Needs work
Parent issue:» #1908570: [meta] Update or create hook_help() texts for D8 core modules

Let's also use this issue to review the whole hook_help text of the Config module.

We are reviewing all the hook_help texts for all D8 modules see #1908570: [meta] Update or create hook_help() texts for D8 core modules.

The current text does not refer to the online docs conform the standard help template, see http://drupal.org/node/632280. It should read For more information, see <a href="!translation">the online documentation for the Configuration Manager module</a>.

Another problem is that the about section mentions the the module "provides a user interface". But we do no explain anything about that UI.

There should be a Uses section (again conform the standard help template, see http://drupal.org/node/632280) to explain what the site admin can do with this module, with links to the UI page(s).

batigolix’s picture

Agree with #5 let see if that http://drupal.org/node/2182101 is necessary if we already have http://drupal.org/documentation/administer/config

It seems that Paul's version is more up-to-date. Is that the case?

paul.linney’s picture

My page only really covers the synchronization page, so yes it could be included on the original config page or they could be split up into subsections:

  • Configuration settings
  • Synchronization
  • Import Export
  • Example Scenarios

If there is agreement on this, then I'll reorganise and fix the help template as suggested and point to the main page (https://drupal.org/documentation/administer/config)

regards,
Paul

mtift’s picture

We are still trying to make configuration synchronization work: #2121751: [META] Making configuration synchronisation work so it is still rather premature to document how synchronization works. The target use case, as well as a link to the META issue, is described on https://drupal.org/documentation/administer/config.

Another key point that needs to be emphasized wherever configuration synchronization is discussed is that (as far as Drupal core is concerned) synchronization will only work between Drupal installations that are the same site. (For more on this, see #2133325: Create a site UUID on install and only allow config sync between sites with the same UUID.)

Conceptually, I'd argue that there is very little difference between "managing configuration" and "synchronizing configuration" and that we don't need two separate documentation pages. In other words, I think updates should be made to http://drupal.org/documentation/administer/config.

paul.linney’s picture

I've updated the https://drupal.org/documentation/administer/config page including the information on the additional post I made and removed the other post.

Doc with all information

regards,
Paul

batigolix’s picture

The other post is this page, right --> https://drupal.org/node/2182101

It has not been removed. You want me to delete it? Or I can move it to ARCHIVE

cheers,
boris

paul.linney’s picture

Hi Boris,

Can you delete please, can't see the option to do it myself.

thanks,
Paul

batigolix’s picture

StatusFileSize
new1.59 KB

Deleted!

I saved the text as attachment here for posterity

Cheers,

Boris

batigolix’s picture

Issue summary:View changes

I added the standard hook_help review task description to the issue summary

jhodgdon’s picture

Status:Needs work» Postponed

Given #9, it seems like maybe we should postpone this issue until the Config module UI is really working?

xjm’s picture

It's working now. :) However, there is a related issue: #2247291: Configuration synchronization UI needs a usability review Leaving postponed on that for the moment.

jhodgdon’s picture

We just had a change to hook_help, on this issue: #2183113: Update hook_help signature to use route_name instead of path.

Here is the change record: https://drupal.org/node/2250345

This patch will need a reroll for this change.

batigolix’s picture

Issue tags:+documentation, +sprint

tagging

jhodgdon’s picture

Instead of having one critical parent issue I have been asked to change the status of each child issue.

This one doesn't seem to major to me. But yes we should get it done. And it still needs to be postponed because hopefully the UI of this area will be revised.

jhodgdon’s picture

Component:documentation» config.module
Priority:Normal» Major

Actually, I think this issue is at least major. There is pretty much no help at all in config_help() currently, and the concept of synchronization *definitely* needs to be explained to the user, as well as something about config storage.

xjm’s picture

Issue summary:View changes
xjm’s picture

jhodgdon’s picture

Title:Improve help text and documentation for CMI imports» Update hook_help() for config manager module
Issue summary:View changes
Status:Postponed» Active

This is currently postponed, apparently just on #2247291: Configuration synchronization UI needs a usability review.

But that issue is not really active right now, so I think we should un-postpone this issue and at least make sure that the Config Manager module has a hook_help() that documents the current state of the module. If the module is later updated, in theory the patch should include an updated hook_help().

For reference in making this patch, we can reference https://www.drupal.org/documentation/administer/config which is the page/section on drupal.org that explains how to use the config manager module.

Also reducing the scope of the title of this issue, because we have #2376749: [META] Update Configuration System Documentation for the larger issue of making sure config is documented in general.

ifrik’s picture

I'll start on this during DrupalDevDays so that we have something that can be changed as appropriate later.

pjonckiere’s picture

Status:Active» Needs review
StatusFileSize
new4.52 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 92,048 pass(es).
[ View ]

I took a stab at this to get us started.

The reference to aggregator_help in the issue summary is probably a copy-paste error?

ifrik’s picture

Status:Needs review» Needs work

Thanks Pjonckiere,
this is a good start.

There are some things that should be changed.

a) in the About section: The default wording linking to the documentation that would be For more information, see the online documentation for the Configuration Manager module.

b) also in the About section: We generally refrain from using "Drupal" in the help texts, because the code can also be used for other distributions and users might not be aware that they are using the Drupal core. So better then " between a Drupal installation in different environments", might be something like "between installations of your website in different environments".

c) "deploy a configuration" - that sounds a bit awkward to me. Maybe leaving out the "a" would be better?

We should explain that all configuration is stored in individual yml files. Then the explanation of what the full import/export does would probably be easier.
I think we should change the order: probably first Full export/import, then single and then synchronisation.

For the single export/import: we need to explain where the copy paste comes from, and what's about the dropdown menus and the Entity ID.

Do you have time to work on this, or is it okay if I have a go at it?

darol100’s picture

Issue summary:View changes
StatusFileSize
new127.76 KB
new4.89 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 92,252 pass(es).
[ View ]

@ifrik

I created a patch that fix A) B) C). In addition, I change the order of the "Uses" just like you mention. I did not explain that all configuration are stored in individual yml files. If you provide me the exact text I would created another file explain that.

Here is an screenshot from all results from this patch.

kim.pepper’s picture

Status:Needs work» Needs review
jhodgdon’s picture

Status:Needs review» Needs work

Thanks for the patch! I don't think it's quite ready to commit though:

a) "Development, Staging and Production" --> we use serial commas in Drupal, so this needs to be "Development, Staging, and Production". The same needs to be done elsewhere too.

b) "so you can make and verify your changes with a comfortable distance from your live environment"... what does this mean? I don't think this belongs in the Help. Stick with describing what the module does and how to use it.

c) In the Uses sections... let's not use the word "feature". Just describe what the module does, and if possible make links to the Admin pages where you can do various things.

d) We have a standard for help that says Uses bullet headers should be -ing verbs, so things like "Importing a foo" not "Import".

e) This generally needs some rewriting... maybe read some of the other core hook_help() pages for ideas about the style, and work on the writing style?

darol100’s picture

If someone provide me the text I can write the patch.

jhodgdon’s picture

Well if you are at DrupalCon LA maybe you can team up with someone who has writing ideas but not patching skills. Otherwise... for more experienced patchers, it is probably just as easy for them to write the text in the form of a patch. ;)

rhuffstedtler’s picture

I'm at DrupalCon LA sitting next to @darol100. I'm going to tackle as much as I can of the items that jhodgdon listed out above starting at a and working down.

rhuffstedtler’s picture

darol100’s picture

Status:Needs work» Reviewed & tested by the community
StatusFileSize
new101.4 KB

@rhuffstedtler,

I have done a great job by re-writing most of the information on that page. In addition, he have added links to indicate the places where he is talking about.

I have attached an interdif.txt to show the difference between his patch and mine and screenshot of this results.

abenamer’s picture

Status:Reviewed & tested by the community» Needs work
+++ b/core/modules/config/config.module
@@ -15,15 +15,60 @@ function config_help($route_name, RouteMatchInterface $route_match) {
+      $output .= '<p>' . t('The single export page can be used to retrieve a single configuration in a yml structure.') . '</p>';

I think yml should be YAML. When referring to snippets of code by language, it should be the formal acronym, one shouldn't use the 3 letter file extension to refer to the code snippet.This is especially the case because the current documentation is referring to a yml (YAML) structure.

Unfortunately, this is not particularly consistent in the rest of the file. For instanced, a gzipped tar file might be better off being called as a .tar.gz file. Files should be referred to by file extension. Conversely, code snippets can be called by the formal acronym of the language.

darol100’s picture

StatusFileSize
new4.98 KB
darol100’s picture

I'm working on this DrupalConLa.

darol100’s picture

Assigned:paul.linney» Unassigned
Status:Needs work» Needs review
StatusFileSize
new5.11 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 94,340 pass(es).
[ View ]

An updated version of this patch with @abenamer suggestion.

jhodgdon’s picture

Status:Needs review» Needs work

Thanks for the work on this patch... But it does not comply with how the other help texts are written or our standards. See http://drupal.org/node/632280 for guidelines, and other modules for examples.

Specific concerns:

  1. +++ b/core/modules/config/config.module
    @@ -15,15 +15,60 @@ function config_help($route_name, RouteMatchInterface $route_match) {
    +      $output .= '<p>' . t('For more information, see the online documentation for the <a href="!url">Configuration Manager module</a>', array(
    +          '!url' => 'http://drupal.org/documentation/administer/config',
    +        )) . '</p>';
    +      $output .= '<h3>' . t('Uses') . '</h3>';

    For better or for worse, in all other hook_help() implementations, these array() calls within t() are all written on one line. Let's do the same here rather than adopting a different format.

    Also, all drupal.org URLs should be
    https://www.drupal.org/*

  2. +++ b/core/modules/config/config.module
    @@ -15,15 +15,60 @@ function config_help($route_name, RouteMatchInterface $route_match) {
    +      $output .= '<dt>' . t('<a href="!url">Exporting a Full Configuration</a>', array(
    +          '!url' => '/admin/config/development/configuration/full/export',
    +        )) . '</dt>';
    +      $output .= '<dd>' . t('Creates a downloadable archive of the active configuration.') . '</dd>';

    The DT elements here should NOT be links. That does not follow our standards of other hook_help() implementations. Put the links in the text.

  3. +++ b/core/modules/config/config.module
    @@ -15,15 +15,60 @@ function config_help($route_name, RouteMatchInterface $route_match) {
    +      $output .= '<dd>' . t('Allows you to upload a full site configuration from an archive file.') . '</dd>';

    The DD sections should describe how to do the thing, and have a link to the page that allows you to do it.

  4. +++ b/core/modules/config/config.module
    @@ -15,15 +15,60 @@ function config_help($route_name, RouteMatchInterface $route_match) {
    +      $output .= '<p>' . t('The full export page can be used to export all configurations of this site, and download them as a gzipped tar file.') . '</p>';

    "configuration" is not really a countable noun, so we shouldn't be referring to "all configurations" of a site. Probably "the full site configuration" would be better?

    Also we really only want to have these on-page help text chunks if the page is unclear in some way in its UI. This one is probably unnecessary, as are the others? I think the page title and the UI give you the same information. Repeating it in help is not actually desirable.

  5. +++ b/core/modules/config/config.module
    @@ -15,15 +15,60 @@ function config_help($route_name, RouteMatchInterface $route_match) {
    +    ¶

    There are empty spaces at the end of this line.

rajneeshb’s picture

Assigned:Unassigned» rajneeshb
Status:Needs work» Needs review
Issue tags:+SrijanSprintDay
StatusFileSize
new5.95 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 94,594 pass(es).
[ View ]

update the patch file with @jhodgdon comments.

RavindraSingh’s picture

@rajneeshb, Please do add interdiff.
https://www.drupal.org/documentation/git/interdiff

Second thing when you are uploading a patch based on others suggestion please update the pointers specifically in the comment. like in you updated patch with covered points.