Convert config module hook_help() to topic(s)

Thanks for the patch and review! However, this patch is not quite ready to go yet. Some things to fix:

a) Navigation: You need to use HTML entities & instead of > in the navigation lines in steps.

b) YAML is mentioned in several topics but is not explained. I think it should be.

c) I don't think "configuration" can be plural (it is not countable). So the heading "What are configurations?" in the overview topic should probably be "What is configuration?". Also the UUID section is confusing to me.

d) config.import_full.html.twig -- I think it should have a link to the export full topic, because that is where it tells you how to export this tar.gz file that you are uploading. I also don't think it is useful to make the synchronize page a link, because without following the steps, you wouldn't see anything useful on that page.

e) Avoid words like "just" and "simply" in help. People are reading help because they need help. These types of words make them think they are stupid for not already knowing how to do things.

f) config.import_single.html.twig -- needs to link to the single export topic. Also needs to explain why you would need to put in a custom entity ID (it currently just says "if required" but doesn't explain why).

g) config.sync.html.twig -- I don't think this makes sense as a separate topic from the full import topic?

h) config_environment.overview.html.twig -- this topic should be merged into the overview topic I think? It has a goal but no steps, so it is not a task topic.

i) Could use a little proofreading.

Thanks for the new patch -- this is definitely an improvement! But please check the Standards for Help Topics.

A few things to fix still:

a) Grammar: missing a lot of a/an/the especially, some extra a/an/the, sometimes singular/plural forms of verbs are mixed up, etc. You might try viewing the topic, and pasting the output HTML into a word processor that has grammar checking for English (this is available as an add-on for Open/Libre Office, and most commercial word processors have that feature too).

b) <h2>{% trans %}Managing UUID{% endtrans %}</h2>
This is not an acceptable heading. Should start with "What is" or "What are".

c) config.import_full.html.twig -- navigation still has one > that needs to be an HTML entity.

d) Click on the <em>Upload</em> button. should just be Click <em>Upload</em> (and similarly for other "Click" instructions).

e) Single import topic:
<li>{% trans %}Paste the YAML structured configuration, which can be created from <a href="{{ single_export }}">Single Export Page</a>.{% endtrans %}</li>
Can we do something like "See (link to the topic name here) for instructions" (with a link to the single export topic name) instead of linking to the admin UI page?

f) This also applies to the full import topic.

I probably cannot review your new patch for a couple of weeks, sorry! Possibly someone else will review. Thanks for making the patch!

There are grammar problems in these topics. Also some standards problems, such as that all UI text needs to be put in EM tags (italics) (such as navigation). I don't have time to itemize all the problems... sorry! I will probably make a new patch in the next few days unless someone else does so first, but I wanted to make sure in the meantime that the patch didn't get committed.

Actually, I just realized the config_environment module is experimental status, so we should not document it yet.

Also, the latest patch here has a bunch of block-related topics in it... seems wrong? Please fix.

The patch in #25 is entirely composed of changes to files that are not related to this issue. Where is the patch with new topics?

OK, thanks! I went back to the patch in #22 and reviewed it. It was pretty good, but needed some grammar cleanup and a few things for standards (see https://www.drupal.org/docs/develop/documenting-your-project/help-topic-... ), so I made a new patch. Since nearly every line in the original patch changed, I did not make an interdiff file (not useful).

Also adding tag, as I worked on this at the MidCamp 2020 virtual contribution day.

The patch in #37 is wrong. The word should be device, not devices. Going back to the patch in #29, which I will re-upload.

Setting back to Needs Review, because I see no indication based on #32 that a full review was done, just that someone verified "it works" which is not what was asked for in the issue summary for a careful review.

Did you follow the instructions for reviewing that are in the issue summary of this issue? I see no indication that you did that, only that you applied the patch and verified the topics could be viewed, which we already knew from the automated test. Please do not set these help topic issues to Reviewed and Tested unless you have done all of the review steps.

Thanks again for the careful review!! You are doing an excellent job and it is much appreciated.

Good points. Here's a new patch that tightens up and corrects those sections of the help topics.

Our help topic standards say that the "Overview" section comes last in this type of topic, and our other topics are following this standard, so I think I'll leave item 2 alone.

Thanks again for clarifying on item 1. How's this? I just took out the sentence you identified as being wrong. I think the section still makes sense, and the important thing is getting across that you can't mix the site UUIDs.

Something interesting came up on #3095737-30: Convert internationalization modules: config_translation, content_translation, locale, language module hook_help() to topic(s) and the following comment: When you translate configuration, you need to understand the difference between "simple" configuration and what we call in code "configuration entities".

I think we should:
a) Decide on the terminology for "configuration entities". On that other issue I called it "list configuration", because the UI for config translation uses the verb "list" for these -- you have to select the type and then list them out, and then you can pick one to translate, as opposed to simple configuration that you can choose directly. penyaskito suggested in Slack to call them "configuration objects". I'm not sure we want to call them "entities", as I think we are trying to avoid that.

b) Add a bit to the config.overview.html.twig topic about this subject.

c) Change the file name to core.config_overview so that it will be visible even if the config manager module is not enabled.

This looks mostly great, thanks! A few suggestions (see also the help topic standards page https://www.drupal.org/docs/develop/documenting-your-project/help-topic-...):

1. Generally, we've been trying to avoid using the word "Drupal" in the UI and help. Some people may use distributions or other means to obscure the fact they are running Drupal, and this is fine. Better wording can be "You can ___" or "Your site ___" or "The core software".

2. Overview topic:
- According to our standards, the headings in overview topics should be questions, except one called "____ Overview"
- The terminology section... some of the explanations seem pretty technical? For example, the YAML entry talks about "serialization", which I'm sure I wouldn't have understood a few years ago.

3. config.import_full:
- The "What is" sections seem to be repeats of information that is on the overview topic? I think the information should only be in one place; I don't feel strongly about which place.

4. I think I saw a few typos but overall it looks great! Will wait to nitpick until the content issues are addressed.

5. See previous comment for an additional piece of information we need to add and a possible name change for the overview topic.

That's a great start! I was going to write something up, but this is much better than what I was thinking. :)

A few thoughts:

a) I don't think we should talk about schema. That is something only a developer cares about.

b) I don't think we should use terms like "boolean" (which if we do use it, needs to be Boolean, capitalized by the way, sorry for the nitpick), or key/value pairs or multi-dimensional arrays. Let's focus on things the end user in the UI would see, which are forms for settings, not the contents of the YAML files.

c) I don't agree that config entities are not seen in the UI. On the contrary, most config entities have a UI for CRUD operations on them, like creating/updating/deleting views.

So maybe we can do something even simpler... for simple config, something more like:

A simple configuration item is a group of settings, such as the settings for a module or theme. Each simple configuration item has its own unique structure.

And for entities:

Configuration entities are user-defined configuration items grouped by type, such as views, image styles, and content types. Each configuration entity within a type has a similar structure.

The test error looks like it is from several places that have:

+related:
+- config.overview

But the topic is actually named core.config_overview.

I went ahead and edited the patch file directly -- just did a search-and-replace for config.overview -> core.config_overview. Let's see if this one passes the tests.

Search test still fails. It seems that the search indexing is failing with the new topics, possibly related to this error:

Warning:       Your XML configuration validates against a deprecated schema.
Suggestion:    Migrate your XML configuration using "--migrate-configuration"!

I have no idea what that is about. ?!? Weird. I did take a look and verified that in Drupal Core without this patch, that message does not appear in the console log, so it seems to be related to this patch.

I tried to debug this a bit. It seems that during the test, it is for some reason stalling/crashing while trying to index the core.config_overview topic.

Ohhhhh... I was going to say I don't know why, but I think I actually do. At the top of this topic is:

+---
+{% set config_sync = render_var(url('config.sync')) %}

This URL is only valid if the config module is installed. That needs to go away. This topic is in the core namespace now, and it can't depend on anything in a non-required module like Config Manager.

This is an overview topic, and there shouldn't be any reason to link to that admin URL or describe specific tasks (those should be left to Task topics). I don't think we should have a heading in that topic saying "Where do I manage configuration?" either -- again, that should be left to task topics.

Oh, should have clarified:

The render_var is a problem. The links at the top under "related" will not cause any problems. Unknown "related" topics are simply skipped during rendering, but the render_var will crash and burn.

And yes, in other overview topics we've had a section at the end called something like "Overview of managing xyz". This section would list the Core modules that provide the relevant functionality, and then have the "see related topics" wording:
https://www.drupal.org/docs/develop/documenting-your-project/help-topic-...

I guess the standards don't currently say anything about listing the core modules, but our existing topics are doing that, at least the recent ones.

So something like "Configuration management functionality is provided by the core Configuration Manager module [or whatever it is called]. See the related topics..."

I don't know what the XML problem is. I thought it was due to the links having invalid href attributes due to the broken render_var, but you got rid of that... Maybe something to do with a faulty German translation of something ... ??? I don't get it. The previous patch (which failed the search test) worked fine on my test site as far as being renderable and searchable.

But in the search test, the cron jobs fail to index the new topics (I debugged it that far). ... ... not sure. Maybe I'll try installing German like the test does, and see if I can still index for search. ??!? weird.

Found it!

<dd>{% trans %}The configuration sync directory location is set in the site's <em>settings.php</em>. When configuration is exported, the active configuration is exported and described in YAML files which are stored in the configuration sync directory. After the first export, the system compares the site's active configuration with the configuration data in the sync directory and will only export active configuration that are different than its counterpart in the sync directory.</dd>

Weird error message, but this dd does not have an endtrans tag!

Let's see what this does. Same patch as #78 but with the endtrans added in that one line as per #83.

I have a feeling that XML error is not from us, but is something that is getting spit out whenever a test fails due to something wrong in the PHPUnit config, because there was a random test fail on that last one that also had that XML error... not sure. Anyway.

That was indeed a weird error. No idea what it was from really. I guess we could add an issue but maybe we should just let it go -- the topic did have a syntax error and the test caught that there was an error, even if it didn't give us useful information about the error.

Anyway, yes I need to make time to review the patch today. Will try to do that!!

Sorry, ran out of time yesterday... Quick content review of the Overview topic -- see also
https://www.drupal.org/docs/develop/documenting-your-project/help-topic-...

a) The headings for the sections in this topic should be "What is..." or "What are..." questions, except the last one. To maintain consistency with other topics, we need to rewrite the "How" headings as "What" instead. Example: How is configuration synchronized between site instances? could be "What is configuration synchronization?" . [The idea of this type of topic is giving background ("what"), not explaining tasks ("how").]

b) The last one should be something like "Managing configuration overview". By convention based on our other topics [this is not in the Standards doc but should be], we've been making a list in this section of which Core modules provide which functionality, and then including the standard "See the related topics listed below for specific tasks." sentence at the end.

c) Avoid the word "Drupal". Use "The core software" instead or mention particular core modules.

d) Themes and installation profiles (not just modules) can also define default configuration.

e) YAML is explained under "How is configuration synchronized between site instances?", but the term is used above that section, so it should probably be explained earlier?

f) I don't think we should mention Drush. We haven't in other Core topics. But I think it's fine to have an Additional Resource link that mentions Drush.

Forgot to say, this is looking very good! I just got into the nitpicking...

apparently I forgot to change the status.

Thanks for the new patch and interdiff! (To prevent automated testing on interdiff files, use a .txt extension next time instead of .patch for the interdiff file.)

The interdiff looks mostly good! I took a look at that and at the patch as a whole, and I found a few minor things to fix (in spite of the number of comments here, really the topics are all in very good shape). These comments are all about the core.config_overview.html.twig topic, except the last suggestion:

1. For the question about YAML from previous reviews: the explanatory information about YAML should be moved to the first mention of YAML in the topic.
2. "Configuration system of the core software enables you" ==> needs to start with "The".
3. "Default configuration can be provided by modules, themes and installation profiles" ==> In the Drupal project, we use "serial commas". So we need a comma before "and" so it says "modules, themes, and installation profiles"

4. +<h2>{% trans %}What is configuration synchronization?{% endtrans %}</h2>
    <p>{% trans %}Each site has unique identifier, also called a <em>UUID</em>, which identifies the site to the system in any instance of the site, as long as the site instances have been reproduced as clones, (in short, the codebase and database are copied to create a new site instance). When site instances are cloned, a "dev" instance of the site has the same UUID as the "live" instance. When site instances share the same UUID, configuration can be exported from one instance to another.{% endtrans %}</p>
   

   It seems like this section's paragraph should start with a sentence explaining what configuration synchronization is, before launching into an explanation of the UUID and how it is used? Maybe something like this:

   Configuration synchronization is the process of exporting and importing configuration to keep configuration synchronized between different versions of a site; for example, between a development site and the live site.

5. +<h2>{% trans %}Managing configuration overview{% endtrans %}</h2>
   +<p>{% trans %}Configuration management tasks can be done either through the administrative UI or using any tool.{% endtrans %}</p>
   

   This "overview" section should do the following:
   a) List which core modules handle configuration management tasks, and list the tasks in brief. So we definitely need to mention the core Configuration Manager module (make sure to verify the name!) and its import/export/synchronize tasks. I think we should also have a sentence something like "Most modules and themes also provide administrative user interfaces for managing their own configuration."
   b) End with the standard sentence "See the related topics listed below for specific tasks."

   I don't think we need the sentence that is currently in the patch at all.

6. The first heading in the topic is "Configuration system overview". That section should be retitled "What is the configuration system?". And the paragraph near the end of that section saying "Configuration management functionality is provided by the core Configuration Manager module. See the related topics listed below for specific tasks." should be removed (see previous item).
7. I think we should take out the words ", as the name implies," in the bullet point about active configuration. This phrase is not really needed and it kind of sounds like we're saying people should already know what "active configuration" is.
8. Nitpick: "module's configuration without interference from the module" -- there are two spaces between "module's" and "configuration".
9. Under "What is configuration data", we have " Default configuration can be provided by modules, themes and installation profiles when they are installed, and those default settings can then be updated by a site administrator using the administrative interface.". I think we should actually take those two sentences out. This information is provided later in the topic in more detail.
10. Under the "Default configuration" bullet point:
    
Default configuration can be defined by a module in their config/install or config/optional directories as YAML files, as either simple configuration or a configuration entity.

a) Should say "by a module, theme, or installation profile in its"
b) "as YAML files, as either simple configuration or a configuration entity" ==> I think this part would be less awkward as a new sentence saying "Configuration consists of YAML files containing simple configuration and configuration entities."

11. The other topics are looking great! I do have one comment: We have to consider that people are possibly going to find these topics through searches. So it is helpful if in the Goal section of the task-oriented topics, we have a sentence like:

    See Managing and deploying configuration for more information about configuration.

    (where "Managing and deploying configuration" would link to the core.config_overview topic). It is helpful to have this in addition to the Related topic link, because it gives people more specific guidance on where to find the overview information.

This is definitely looking close!! Thanks to both of you for the patches.

I took a look at the latest patch, and I have a few comments/suggestions:

a) in the overview topic:

+<h2>{% trans %}What is configuration data?{% endtrans %}</h2>
+<p>{% trans %}Configuration data describes settings that define how your site behaves or is displayed. For example, when a site administrator updates settings using an administrative form, these settings are stored as configuration data. Configuration data describes settings as simple as a site name and as complex as a view or image style.{% endtrans %}</p>
+<dl>
+  <dt>{% trans %}YAML{% endtrans %}</dt>
+  <dd>{% trans %}YAML is a human-readable data serialization standard that can be used in conjunction with all programming languages. In the core software, YAML is used to describe various meta-information, routing, menu items, as well as configuration data. Files in a your site's codebase with the extension <em>.yml</em> are in YAML-format.{% endtrans %}</dd>
+</dl>

This seems a bit weird. The section is called "What is configuration data". The first paragraph does not mention YAML (which is fine). And then suddenly there is (with no introduction) a DL list with a definition of YAML. ????

The first actual mention of YAML is actually in the next section, entitled "What kinds of configuration are there?", in the last item in the list "Default configuration". So maybe what we should do is rewrite that DD to say something like:

<dd>{% trans %}Default configuration can be defined by an extension (module, theme, or installation profile) in its <em>config/install</em> and/or <em>config/optional</em> directories. Configuration is provided in YAML files (file extension .yml); YAML is a human-readable data serialization standard that is used by the core software for several purposes. Once the default configuration has been imported into the site's active configuration (through installing the extension), that configuration is owned by the site, not the extension. This means that future updates of the extension will not override the site's active configuration for that extension.{% endtrans %}</dd>

I made several other suggested changes to that paragraph, which I think make it read clearer?

b) in Overview topic in section "Managing configuration overview" -- we should mention that the adminstrative UI for configuration import/export/sync is provided by the core Configuration Manager module. So:
"can be done either through the administrative UI" ==> "can be done either through the administrative UI provided by the core Configuration Manager module".

c) In the export_single topic: I think in the Goal section we should say "Export a single configuration item to a file.". I guess that is understood, but we don't have "to a file" in there? Best to be explicit?

The rest all looks great!!!

This looks great to me! I haven't actually tested the patch on a live site to make sure all the links go to the right places and the UI text mentioned in the topics matches what you see in the UI. So I haven't yet marked it RTBC. But I will make time to do that in the next day or two.

I hate to do this... but although these topics seem very good, I think we need to change a few more things -- all very minor except the first item:

a) As I read through the help topics in this patch on an actual site... I started at core.config_overview (which is the only top-level topic). The first section is "What is the configuration system?", and it talks about moving and synchronizing changes as being the main functions of the core configuration system.

However, really the main function of the configuration *system* is to manage the site's configuration. The main function of the core Configuration Manager module is to move/synchronize changes.

So, I think we should change that first sentence. Maybe something like:

The configuration system provides the ability for administrators to customize the site, and to move and synchronize configuration changes between development sites and the live site.

b) in the overview topic, first section: "... between instances of the same site, for example, from" ==> should be a semicolon before "for example", not a comma

c) overview topic, under "Active configuration": I think we could say "of a site" rather than the more convoluted "of an instance of a site"?

d) overview topic under "What is configuration synchronization", second paragraph: "... as clones, (in short," -- should not be a comma before the parenthesis.

e) Also at that same spot... I think the parenthetical remark "in short, the codebase and database..." would be better as "cloning is when the codebase and database...".

f) in that section under "Configuration sync directory": "is set in the site's settings.php" I think should say "settings.php file".

g) same area, next sentence: "will only export active configuration that are different than its counterpart" ... this has some singular/plural confusion between the verb "are" and the pronoun "its" and noun "counterpart". How about "will only export active configuration items that are different than their counterparts"? We use the term "configuration item" elsewhere in these topics.

h) First paragraph under "Managing configuration overview" I think should end with the word "file" (settings.php file) and it also needs a . at the end.

i) For future proof-ness, I don't think the topic number (1.5, 11.7, etc.) should be included in the link text when making links to the User Guide. Those numbers sometimes change as we add topics.

The rest looks great! I didn't find even anything minor in the task topics. Great work everyone!

This should not really be a Novice issue unless we want to recruit a group of novice contributors to follow the review instructions.

Looks great!

I will note that on #2144861: [meta] Replace Drupal in UI text with the name of the distribution we are trying to get rid of the word "drupal" from UI text, so we'll eventually probably want to say "User Guide" rather than "Drupal User Guide" (although Drupal User Guide is the name of the guide, so ... not sure about that). But we have two items related to this on #3121340: Fix up minor copy problems in help topics (not using the word Drupal and also making links to the User Guide consistent across topics), so for now let's leave this as it is. Thanks for all the patches!

a) Are you backporting all the topics commits? Because we don't want to end up with an inconsistent set of topics/tests in 9.1/9.2. Might be better to just commit to the latest branch. I hadn't noticed other Help Topics patches being committed to two places (but maybe just didn't notice).

b) I added the follow-up note to #3121340: Fix up minor copy problems in help topics