Convert content_moderation, workflows module hook_help() to topic(s)

Parent issue was committed, so we can un-postpone this now!

Adding some related modules to this issue. Also there is no patch so the status is Active (my fault).

Updated issue summary with better instructions/guidelines

Another iteration on guidelines.

I would like to work on this one.

We've migrated the help topic standards to https://www.drupal.org/docs/develop/documenting-your-project/help-topic-... so updating issue summary again.

Since there was no activity on this so picked this issue. I have added overviews for required modules in this issues. Please Review. Thanks!!.

Thank you for the patch!

I have reviewed the text in the patch file. I did not test applying the patch and viewing the help topics, so that will need to be done eventually.

But for now... It looks like you just took the documentation in the hook_help and copied it into the new Twig format. That is not actually what we want in topics. Please read the issue summary here and follow the instructions and guidelines there to make good help topics. Thanks!

In particular, we probably want to have 1 overview topic for this issue that explains all the background information, such as:
- What is a workflow state?
- What is a workflow transition?
- What is a workflow?
- Overview of content moderation using workflows

And then we would need to have several task-oriented topics that would explain how to accomplish various tasks, like setting up workflow states, defining the workflow transitions, setting permissions for content moderation, and moving a piece of content through a workflow transition. Or something like that?

So... Please start over...

Tagging for badcamp2019, thanks! (October 2-5)

We just found out that all topic Twig files currently need to go into core/modules/help_topics/help_topics (with their finalized module-based file names), for the time being until the Help Topics module is stable. Updating issue summary. Patch will need to be updated too.

Moving the files as per #13 to core/modules/help_topics @ Amsterdam2019

After applying the patch, an error was thrown regarding the missing `front matter`, I checked other issues to get the correct syntax. I replaced the tags with the yml front matter.

i.e.

<meta name="help_topic:label" content="Workspaces"/>
<meta name="help_topic:top_level"/>

to

---
label: 'Workspaces'
top_level: true
---

Then I moved the files into the help_topics path.

The still needs wording update as per #10.

Just realized the workspaces module is experiemental, so we probably don't want to document it yet.

The patch (3047722-16.patch) has been applied on 9.1.x branch cleanly.

I'm trying to reword this for topics and will add a patch soon.

Adding a patch as per suggested changes in #10. I still feel this needs a lot more to be added. Adding a draft now :)

Thanks for the patch!

According to our Standards for Help Topics, a Task topic should have a one-sentence Goal section, and then a Steps section telling the steps to follow to achieve the goal. This topic has a Goal section that is a bullet list... it is really a "Section" topic providing background information, but it isn't following the standards for the headings of that type of topic either.

What we really need here is:
- 1 Section topic that gives an overview of content moderation and workflows, and follows the Standards.
- Several Task topics that follow the Standards to provide the steps for related tasks, such as setting up workflow states, defining the workflow transitions, setting permissions for content moderation, and moving a piece of content through a workflow transition.

@jhodgdon, Thanks for your inputs. This was an initial draft. Will update soon.

@mohrerao: Please let me know if you are still planning to make a new patch for this. If not, I will have some time this week and can work on it.

@jhodgdon, working on it today

@jhodgdon, Have made changes as requested. Please review.

Please ignore previous patch. Updating patch for failed test .

Please read #24 again. This is still not what we need, and it still doesn't follow the standards.

Here is a new patch, which adds 3 topics: 1 overview and 2 task topics, as requested in #24.

One note: there seems to be a bug in the content moderation overview page. We'll need to look into that. I couldn't get admin/content/moderated to ever show me any content that needed moderation. Maybe this is a problem with just my site, I'm not sure...

It turns out that the content moderation overview page is hard-wired to work only with nodes, and only if the content types are set up to be moderated using the default states provided by the default workflow provided by the Standard install profile.

So if you edit the default workflow or create your own, or if you are moderating something like Custom Blocks, or if you did not install using the Standard profile, that view page is useless.

Therefore, the topic about "Moving content between workflow states" in this patch needs some work. I think the best option is not to mention this fairly problematic view page at all, and just to direct people to find their content item using admin/content, or their custom block in the block library, or whatever.

Other thoughts on this patch:

a) The topic about configuring a workflow should start with a step about planning the workflow: decide on names for the states, how to transition between them, which one(s) are "published", and who should have permission to make the transitions. Then the rest of the steps will make more sense I think.

b) The topic about configuring definitely needs to have a final step about optionally making a view to show unmoderated content, with a few hints on how to make that view. And say if you don't do that, you'll need to set up some kind of email notification process or spreadsheet or something so people who need to review content know that there is content to be reviewed and how to find it.

c) The topic about moderating content should start by saying to go to the view page if you made one, or else find the content to be moderated using the process you set up.

So I think we should postpone this until the views topic help is done.

Views topics commited

@jhodgdon can we have multiple Goals in one topic

No. Please read the help topic guidelines, where it explains what a Task topic is: one goal, one set of steps.

should we have to add more topics in this issue or update the patch as per comment in #37

I don't think we need more topics. The existing topics need to be edited as per #36 and #37. We could also have a new topic that explains how to make a content moderation view page.

Changes done as per #36
directed people to find their content item using admin/content in the topic about "Moving content between workflow states".

I have few observation in #37(a)
Since we need to set 'states' after workflow is created so i think steps about creating states in at correct place

also added new topic that explains how to make a content moderation view page.

I have checked patch #44 working fine. I think good to go +1 RTBC.

Thanks for the new patch!

What I meant in #37 a is that we need a step that is about thinking and planning, before we start in on the doing. I still think we need that. Without that step, the whole thing is pretty mysterious.

The views topic is a good start! But we already have a topic that covers how to make a view. This topic should link to that topic rather than repeating the basic information that is there. Right now it says to edit the view "edit it following the steps in the related topics below" but there are no related topics about editing views.

There are also some grammatical issues in this patch, but I think I'll wait until the content is closer before critiquing grammar.

Tagging this for DrupalCon Global happening July 14-17

These writing tasks are not really Novice level.

I'll give this a try

This patch can be reviewed.

The following changes were made:
- remarks from #36 & #37 & #48 incorporated
- views topic removed. after removing the general views instructions there was very little workflows specific information left, so I decided to remove the topic
- topic titles and topic filenames changed

I did not provide an interdiff because of the large amount of changes.

Apologies to earlier authors for throwing out some parts of their work.

Thanks! This is looking much better. A few small suggestions (see https://www.drupal.org/docs/develop/documenting-your-project/help-topic-...):

a) workflows.overview topic:
1. Title should start with a verb, like all the other topic titles
2. Generally we try to avoid using the word "Drupal" in help, so that the branding is not there, just in case someone is trying to build an application with different branding.
3. Overview topics should have a section called "Overview of ____" that lists the tasks you might do and what each core module does in the process (we need to talk about both the Workflows module and the Content Moderation module here). See item 4 on the "Parts of a section topic" on the standards page, or most of the other top-level topics for examples.

b) content_moderation.configuring_workflows topic:
1. Step 2 "A list with workflows is being shown." ==> "is shown" (instead of is being shown)
2. Step 16 -- link with text "Modifying the permissions for a role" does not work.
3. Step 17 -- there are two links with different text that both go to the topic on creating views... this doesn't seem right?
4. Step 17 -- "When creating the view ensure to select " ==> "be sure to select" (instead of ensure to select)
5. Step 17 -- It says to be sure to select a data type that has revisions, but shouldn't it say to choose one of the data types you configured in step 11/12 to work with this workflow? And maybe in steps 11/12 we should say that it has to be an entity type that supports revisions?
6. I think the Creating a view topic should be marked as Related?
7. It would probably also be useful in the Goal section to have a link back to the overview of workflows topic, something like "See [name of topic] for more information on workflows".

c) content_moderation.changing_states
1. Step 1 says to open the content moderation list page. ... maybe it should say "view page" instead, since the other topic talked about creating a view, not a list page?
1. Step 1 -- "The list of all the site's content is being shown." ==> "is shown"
1. Step 1 assumes that the view you created has operations. We should mention that in the other topic -- it seems like we may need a bullet list of things to do in your view in the last step of that other topic?

Looks pretty good overall though!!

I have tried to implement changes as per the suggestions in #54 except the below points

b) content_moderation.configuring_workflows topic:
3. Step 17 -- there are two links with different text that both go to the topic on creating views... this doesn't seem right?
5. Step 17 -- It says to be sure to select a data type that has revisions, but shouldn't it say to choose one of the data types you configured in step 11/12 to work with this workflow? And maybe in steps 11/12 we should say that it has to be an entity type that supports revisions?

c) content_moderation.changing_states
1. Step 1 assumes that the view you created has operations. We should mention that in the other topic -- it seems like we may need a bullet list of things to do in your view in the last step of that other topic?

Please review.
Thank you

Thanks! Most of the changes in the interdiff look good. Setting back to needs work because the changes were not complete (see previous comment), and also to fix these minor things from the new work:

a) core/modules/help_topics/help_topics/content_moderation.configuring_workflows.html.twig

... for more information on workflows{% endtrans %}</p>

Missing . at end of sentence.

b) Same topic:

A list with workflows is shown

with ==> of

Thank you for reviewing.
I have made the changes mentioned in #56

Keeping the status as needs work since the below points are remaining

b) content_moderation.configuring_workflows topic:
3. Step 17 -- there are two links with different text that both go to the topic on creating views... this doesn't seem right?
5. Step 17 -- It says to be sure to select a data type that has revisions, but shouldn't it say to choose one of the data types you configured in step 11/12 to work with this workflow? And maybe in steps 11/12 we should say that it has to be an entity type that supports revisions?

c) content_moderation.changing_states
1. Step 1 assumes that the view you created has operations. We should mention that in the other topic -- it seems like we may need a bullet list of things to do in your view in the last step of that other topic?

Thanks, interdiff looks good. Do you have questions on how to fix the remaining points?

Thanks to review !

I have tried to address the below points in the patch mentioned in #57

b) content_moderation.configuring_workflows topic:
3. Step 17 -- there are two links with different text that both go to the topic on creating views... this doesn't seem right?
5. Step 17 -- It says to be sure to select a data type that has revisions, but shouldn't it say to choose one of the data types you configured in step 11/12 to work with this workflow? And maybe in steps 11/12 we should say that it has to be an entity type that supports revisions?

Please review

The below point is still left, it would be great if you could help bit more on this

c) content_moderation.changing_states
1. Step 1 assumes that the view you created has operations. We should mention that in the other topic -- it seems like we may need a bullet list of things to do in your view in the last step of that other topic?

Thank you

Looks pretty good on the fixes for (b) 3 & 5. Thanks! One sentence needs two very small fixes:

find the entity type that has revisions, such as Content revisions, Custom Block revisions or Taxonomy term revisions and you want this workflow to apply to

Two things to fix here:
1. We use the "Oxford comma" in the Drupal project. So there should be a comma in "... Custom block revisions, or Taxonomy...".
2. "Taxonomy term revisions and you want" => "that you want".

What I meant on (c) is taht in the configuring_workflows topic, in step 17 where it says to create a view, we should add a note that your view should have a bulk operations thing... you'll need to try this out and see what it's really called in the Views user interface.

Thanks!

Fixed the two small fixes.
Forthe last point, if I'm not wring, are we mentioning about creating a view similar to what Drupal provides for the moderated content listing => /admin/content/moderated ?

Attaching files again.

Two small fixes look good, thanks!

And yes... The admin/content/moderated view only works with the default workflow that is provided by the core modules. So if you create your own workflow, you need to start over and connect it to your workflow, but it should look similar to the view that the core modules provide at admin/content/moderated.

I read through these topics again, and I think it is very close! There are several small things that need to be fixed:

1. content_moderation.changing_states.html.twig : The link in the first step where it says Read <em><a href="{{ content }}">Managing Content</a></em> is going to the admin/content page. Based on the sentence and the link text, it should be linking to a topic about managing content.
2. workflows.overview.html.twig : This is a very small problem, but in some places this topic refers to "workflows" or "a workflow" (which I think is fine). But near the end is this sentence: "The core Workflows module allows you to manage workflow with states and transitions.". To be consistent with the rest of the topic, it should say "... manage workflows" not "manage workflow".
3. content_moderation.configuring_workflows.html.twig :
   a. In US English, we never write out "et cetera". Change this to "etc.".

   b. In the planning step, the verb is "List" but I think it should mostly be "Decide".

   c. This sentence seems awkward: "Also plan in which state the content will be published and which state will be the default revision.". Maybe change it to:
   Also decide which state means that the content is published, and which state should be the default revision.

   d. This seems a bit off: "List which state transitions the users will be able to choose from" -- it's not so much that they choose from transitions, it's that they create content in one state, and then move content between states. So maybe change this to:

   Decide on the list of allowed transitions. For example, users might create content in state "Concept" and be able to make a transition from "Concept' to "Review".

   e. "Custom Block revisions, or Taxonomy term revisions" -- inconsistent capitalization here. Probably should be "Custom block revisions", but check the UI to see what it says there.

   f. Since the Views UI module is not a dependency of the Content Moderation module, we cannot make a direct link to a Views UI module using the Twig url() function in this topic -- it will crash if the Views UI module is not currently enabled. So this line needs to go away:
   {% set creating_view = render_var(url('help.help_topic', {'id': 'views_ui.create'})) %}
   And the line that refers to this topic also needs to change:
   Find out how to add a view by following the instructions in the <em><a href="{{ creating_view }}">help topic on creating views</a></em>.

   Actually I would suggest a rewrite of that whole step. My suggested text would be:

   <li>{% trans %}Optionally (recommended), create a view for your custom workflow, to provide a page for content editors to see what content needs to be moderated. You can do this if the Views UI module is installed, by following the steps in the related Find out how to add a view by following the instructions in the <em>Creating a new view</em> topic listed below under <em>Related topics</em>. When creating the view, under <em>View settings</em> &gt; <em>Show</em>, select the revision data type you configured the workflow for, and be sure to display the Workflow State field in your view.{% endtrans %}</li>
   

   I'm not entirely sure about the last few words of this -- not sure what the field is called when you add it in views -- so someone needs to check the UI and see if it is called "Workflow State" or something else, and make sure the UI matches the help text.

Here's a new patch. A few notes beyond the previous review, related to content_moderation.changing_states:
- We cannot make links in topics using the Twig "set" function that go to admin pages or topics that are defined in modules that are not dependencies of the module in question. This is a topic in the content_moderation module; the only dependency is the Workflows module (which has no dependencies). So in particular, we can't link to the (as yet undefined anyway) topic on managing content.
- Also, this topic was written specifically assuming you wanted to moderate Node module content items, which is not necessarily the case (it could be comments, custom blocks, etc.).

Also I cleaned up some wording in a few more places.

What needs to be done in the review is to verify that the text in the steps, especially in content_modreation.configuring_workflows, matches what is shown in the UI (and that the steps work). I was going to try simplytest.me to test this today, but it failed to launch.
#3181350: [InvalidArgumentException] Package szeidler/composer-patches-cli at version ~1.0 has a PHP requirement incompatible with your PHP version, PHP extensions and Composer version

All changes look good to me. Just one nitpick.

+++ b/core/modules/help_topics/help_topics/content_moderation.changing_states.html.twig
@@ -0,0 +1,18 @@
+{% set content_moderation_permissions = render_var(url('user.admin_permissions', {},{'fragment': 'module-content_moderation'})) %}

+++ b/core/modules/help_topics/help_topics/content_moderation.configuring_workflows.html.twig
@@ -0,0 +1,45 @@
+{% set content_moderation_permissions = render_var(url('user.admin_permissions', {},{'fragment': 'module-content_moderation'})) %}
+{% set workflows_permissions = render_var(url('user.admin_permissions', {},{'fragment': 'module-workflows'})) %}

Nitpick: Needs a space between "{}," and "{'fragment"

Thanks for the review! Here's an interdiff and a new patch.

As a note, before setting this issue to RTBC, someone needs to go through the review steps in the issue summary. Thanks!!

I followed the whole howto review this patch and it all looks good to me. Just 2 remarks:

1. +++ b/core/modules/help_topics/help_topics/workflows.overview.html.twig
   @@ -0,0 +1,23 @@
   +{% set entities = render_var(url('help.help_topic', {'id': 'core.content_structure'})) %}
   +{% set users = render_var(url('help.help_topic', {'id': 'user.overview'})) %}
   

   These links are not used.

2. +++ b/core/modules/help_topics/help_topics/content_moderation.changing_states.html.twig
   @@ -0,0 +1,18 @@
   +  <li>{% trans %}Find the content that you want to moderate in either the content moderation view page, if you created one, or the appropriate administrative page for managing that type of content (such as the <em>Content</em> administration page where you can manage content items from the core Node module).{% endtrans %}</li>
   

   Could we make "Content administration page" into a link to that page.

Thanks for the review! Great points.

For the first one, I decided also to add one of the topics as Related, although there is not a specific link to it within this topic.

For the second one, I did make it a link. Links from other modules can be problematic, but in this case admin/content is actually in the system module routing, so we're OK.

I followed the review process as described in the IS.
All 3 twig files look good to me.
For me it is RTBC.

1. +++ b/core/modules/help_topics/help_topics/content_moderation.changing_states.html.twig
   @@ -0,0 +1,19 @@
   +<h2>{% trans %}Steps{% endtrans %}</h2>
   +<ol>
   +  <li>{% trans %}Find the content that you want to moderate in either the content moderation view page, if you created one, or the appropriate administrative page for managing that type of content (such as the <a href="{{ content }}">Content</a> administration page where you can manage content items from the core Node module).{% endtrans %}</li>
   +  <li>{% trans %}Click <em>Edit</em> to edit the content.{% endtrans %}</li>
   

   Does this need to mention 'Node' module - can it just say 'the Content administration page where you can manage content items'? The main reason that we're mentioning node module here seems to be that we're using 'content' to mean 'entities', then using 'content' to mean 'nodes' - could we use 'entities' to mean entities then content for nodes?

2. +++ b/core/modules/help_topics/help_topics/content_moderation.configuring_workflows.html.twig
   @@ -0,0 +1,45 @@
   +    </ul>
   +  </li>
   +  <li>{% trans %}In the <em>Manage</em> administrative menu, navigate to <em>Configuration</em> &gt; <em>Workflow</em> &gt; <a href="{{ workflows_url}}"><em>Workflows</em></a>. A list of workflows is shown, including the default workflow <em>Editorial</em> that you can adapt.{% endtrans %}</li>
   +  <li>{% trans %}Click <em>Add workflow</em>.{% endtrans %}</li>
   +  <li>{% trans %}Enter a name in the <em>Label</em> field, select <em>Content moderation</em> from the <em>Workflow type</em> field, and click <em>Save</em>.{% endtrans %}</li>
   +  <li>{% trans %}Verify each entry in the <em>States</em> list by clicking <em>Edit</em> under <em>Operations</em>. Verify or update the state's <em>State label</em>, and verify that the checkboxes for <em>Published</em> and <em>Default revision</em> are correct. If <em>Published</em> is checked, when content reaches this state it will be made visible on the site (to users with permission). If <em>Default revision</em> is checked, when content reaches this state it will become the default revision of the content; published content is automatically the default revision. Click <em>Save</em> to return to the workflow.{% endtrans %}</li>
   +  <li>{% trans %}If there are entries in the list of <em>States</em> that you do not want, you can delete them by clicking <em>Delete</em> under <em>Operations</em>. If the <em>Delete</em> option is not available, you will first need to delete any <em>Transitions</em> to or from this state.{% endtrans %}</li>
   +  <li>{% trans %}If there are missing states, click <em>Add a new state</em> to add them (see above for information on the settings for each state).{% endtrans %}</li>
   +  <li>{% trans %}When the list of states is correct, verify the entries in the list of <em>Transitions</em>. For each entry, click <em>Edit</em>. Verify or update the states that the transition goes <em>From</em> and <em>To</em>, and then verify that the <em>Transition label</em> makes sense for a transition between these states. Click <em>Save</em> to return to the workflow.{% endtrans %}</li>
   +  <li>{% trans %}If there are entries in the list of <em>Transitions</em> that you do not want, click the <em>Delete</em> link under <em>Operations</em> to delete them.{% endtrans %}</li>
   +  <li>{% trans %}If there are missing transitions, click <em>Add a new transition</em> to add them (see above for information on the settings for each transition).{% endtrans %}</li>
   +  <li>{% trans %}Under <em>This workflow applies to:</em>, find the entity type that you want this workflow to apply to, such as Content revisions, Custom block revisions, or Taxonomy term revisions. Click <em>Select</em>.{% endtrans %}</li>
   +  <li>{% trans %}Check the entity sub-types that you want to apply the workflow to. For example, you might choose to apply your workflow to the <em>Page</em> content type, but not to <em>Article</em>.{% endtrans %}</li>
   +  <li>{% trans %}Click <em>Save</em>.{% endtrans %}</li>
   +  <li>{% trans %}Under <em>Workflow settings</em>, select the <em>Default moderation state</em> for new content.{% endtrans %}</li>
   +  <li>{% trans %}Click <em>Save</em> to save your workflow.{% endtrans %}</li>
   +  <li>{% trans %}Follow the steps in <a href="{{ permissions_topic }}">Modifying the permissions for a role</a> to assign permissions for each transition to roles. The permissions are listed under the <em><a href="{{ content_moderation_permissions }}">Content Moderation</a></em> section; there is one permission for each transition in each workflow.{% endtrans %}</li>
   +  <li>{% trans %}Optionally (recommended), create a view for your custom workflow, to provide a page for content editors to see what content needs to be moderated. You can do this if the Views UI module is installed, by following the steps in the related <em>Creating a new view</em> topic listed below under <em>Related topics</em>. When creating the view, under <em>View settings</em> &gt; <em>Show</em>, select the revision data type you configured the workflow for, and be sure to display the Workflow State field in your view.{% endtrans %}</li>
   +</ol>
   diff --git a/core/modules/help_topics/help_topics/workflows.overview.html.twig b/core/modules/help_topics/help_topics/workflows.overview.html.twig
   

   I find this very hard to follow. I don't think it's the fault of the text as such, but this is a very dense admin section so it is a lot of text and terms all at once. I guess you could have it open in a tab, but I'm not sure if it will actually help people otherwise. Seems like a possible candidate to convert to a tour (which could be linked to from the help topic).

Updated patch in #70 addressing #72.1. Thanks!

Thanks for attempting a fix for item #72.1. However, I don't think this fixes the problem of using the word "content" to mean several things. We need to use the word "entity". Here's a new patch; I started over with the previous patch so the interdiff is to that.

Regarding the complexity of the other topic, I agree it is complex... I reorganized it to hopefully make it easier to follow, by moving the information about the specifics of fields on states/transitions to the Planning item.

I do think it's important to have help topics (not just tours) about all the tasks (and that has been our mandate). Not everyone will (a) have the Tours module installed or (b) really be able to use Tours (there are usability/accessibility issues).

The points of @catch have been addressed.
I like to extension of how to plan a workflow. It makes the rest of the steps more clear.
Back to RTBC.

Things still get a bit confusing between content/node and entity reading the whole thing, but that seems to be more down to us having called entity_moderation module content_moderation so don't think it's the fault of this patch.

Committed/pushed to 9.2.x and cherry-picked to 9.1.x, thanks!