Contrib.social

Fix up minor copy problems in help topics

Open on Drupal.org →
Created on 21 March 2020, over 4 years ago
Updated 18 August 2023, 10 months ago

Problem/Motivation

As help topics have been added, minor errors, typos, and updates were pointed out. This issue was opened to collect these. Many of the issues listed here were fixed in other issues. And some new issues were opened because they needed specific attention or review. The fixes that remain in this issue are copy edits and link text updates, especially with regard to User Guide links, to ensure consistency.

Historically, this issue was more of a meta/plan to collect minor issues. Those are listed under "Original issue summary". Related issues are still listed in the related issues field.

Steps to reproduce

N/A because these are copy edits.

Proposed resolution

Make copy edits to correct minor word usage or UI-text style guide errors (related to the word "Drupal"), ensure consistency of links to the User Guide, and ensure links to the Drupal Wiki with "8" are corrected to the current path and title.

Remaining tasks

  1. DONE -Triage the problems listed in the original issue summary.
    • DONE -Validate problems: mark FIXED problems and link to issue where problem was fixed or OUTDATED if the problem no longer exists.
    • DONE -Open new issues for substantive content problems that need separate discussion. Add issues as Related issues (not child issues) to this issue.
    • DONE -Decide on WON'T FIX problems
    • DONE -Decide if this issue should be a plan/meta or if it can be an issue with a defined, limited scope. (Decision: scoped issue with patch)
    • DONE -Choose the problems that are in-scope (labeled as PATCH in Original issue summary)
    • DONE -Update issue summary with clear scope and review guidelines.
  2. DONE -Update links to the User Guide and make them consistent. Use the page title (without the number, which is subject to change) followed by "(Drupal User Guide)". Page titles should be in title-case (matching the case of the page title).
  3. DONE -Update Links to the Drupal Wiki that have "8" in the path (i.e. "docs/8") or "Drupal 8" in the title. They should be updated to the current URL and page title.
  4. DONE -In the help topic file, core.maintenance.html.twig: In the phrase, "When performing maintenance, such as installing, uninstalling, or upgrading a module...", change upgrading to updating.
  5. DONE -In the help topic file, shortcut.overview.html.twig: In the phrase, "Make sure that the core Shortcut module is enabled...", change enabled to installed.
  6. DONE -Where "Drupal" is used, update to "core software", except when referencing the "Drupal User Guide", because that is the proper name of that resource. Ensure grammatically correct usage.

User interface changes

Help topic text is changed.

API changes

None.

Data model changes

None.

Release notes snippet

<p>In 
            
              
              
              📌
              Fix up minor copy problems in help topics
                Fixed
              
            , the following help topics have been updated to correct minor copy problems, to ensure consistent link text, and to bring copy inline with UI-text standards around the use of the word "Drupal" to describe the core software.</p>

<ul>
  <li>core/modules/block/help_topics/block.overview.html.twig</li>
  <li>core/modules/breakpoint/help_topics/breakpoint.overview.html.twig</li>
  <li>core/modules/help/help_topics/core.appearance.html.twig</li>
  <li>core/modules/help/help_topics/core.config_overview.html.twig</li>
  <li>core/modules/help/help_topics/core.content_structure.html.twig</li>
  <li>core/modules/help/help_topics/core.cron.html.twig</li>
  <li>core/modules/help/help_topics/core.extending.html.twig</li>
  <li>core/modules/help/help_topics/core.maintenance.html.twig</li>
  <li>core/modules/help/help_topics/core.menus.html.twig</li>
  <li>core/modules/help/help_topics/core.performance.html.twig</li>
  <li>core/modules/help/help_topics/core.security.html.twig</li>
  <li>core/modules/help/help_topics/core.ui_components.html.twig</li>
  <li>core/modules/help/help_topics/core.web_services.html.twig</li>
  <li>core/modules/migrate/help_topics/migrate.overview.html.twig</li>
  <li>core/modules/node/help_topics/node.creating_content.html.twig</li>
  <li>core/modules/node/help_topics/node.creating_type.html.twig</li>
  <li>core/modules/node/help_topics/node.editing.html.twig</li>
  <li>core/modules/path/help_topics/path.creating_alias.html.twig</li>
  <li>core/modules/path/help_topics/path.overview.html.twig</li>
  <li>core/modules/shortcut/help_topics/shortcut.overview.html.twig</li>
  <li>core/modules/system/help_topics/system.cache.html.twig</li>
  <li>core/modules/system/help_topics/system.reports.html.twig</li>
  <li>core/modules/taxonomy/help_topics/taxonomy.configuring.html.twig</li>
  <li>core/modules/taxonomy/help_topics/taxonomy.overview.html.twig</li>
  <li>core/modules/views/help_topics/views.overview.html.twig</li>
  <li>core/modules/views_ui/help_topics/views_ui.edit.html.twig</li>
</ul>

Original issue summary

We have made a few typos and there may be other minor problems with help topics to fix up... This issue is to collect them.

Here is the list of fixes to do:

  1. FIXED 📌 Fix wording aroud 403/404 in help topic Fixed
  2. FIXED 🐛 Update topic contact.setting_default to use route instead of "/contact" Fixed
  3. MOVED TO 📌 Create or update help topics that cover CKEditor 5's module overview text in hook_help() Active
  4. MOVED TO 📌 Create or update help topics that cover CKEditor 5's module overview text in hook_help() Active ) - On #3150364: Add a description for the language toolbar button to the CKEditor help page → they also made a list of accessibility features and a section about making accessible text. I'm not sure we covered that well in our topic on Accessibility, so we should check. See this screenshot of the output of one of the patches:
  5. WON'T FIX - On #3067727: Convert comment, node, path, taxonomy module hook_help() to topic(s) → , the patch on #41 introduced the idea of adding a "Who can...?" section between Goal and Steps on Task topics, which tells what permissions you need to do the task. This seems like a good idea that maybe we should replicate on other Task topics?
  6. WON'T FIX - On #3047711-43: Convert file, image, media, media_library, responsive_image module hook_help() to topic(s) → , catch brought up the question of terminology to use for "bundles" (entity sub-types). We had adopted (in the core.structure topic) the terminology of calling them "entity sub-types", as we did in the User Guide. On 📌 Rename entity "bundle" to "subtype" in the UI text and help Postponed: needs info we decided that we should call things like Node, Taxonomy, etc., if we needed to talk about them as a group, "Entity types". Things like "Content type", "Vocabulary" we should call "Entity subtypes" if we need to talk about them as a group. Things like a node, a taxonomy term, etc. should be called "Entities". I believe we mostly have adopted this terminology in our help topics, but we should check and make sure -- we may have used the terminology "Entity item" instead of "Entity" for the individual items, and "sub-type" instead of "subtype".
  7. OUTDATED - Checked on 22 Jun 2023 and "menu items" and "menu entries" (and their derivatives) not found. 📌 UI: Rename 'menu items' to 'menu links' for more consistency Needs work
  8. PATCH - We have a number of links from topics in the Additional Information sections that go to drupal.org pages (either in the main docs or the User Guide). The link text is not consistent. Some of them have link text like "User Guide: Title of Topic" and others have link text like "User Guide topic on Title of Topic". We should standardize this. Easy to find -- grep for user_guide in the topics. The standard is to use the page title (without the number, which is subject to change) followed by "(Drupal User Guide)". Page titles should be in title-case (matching the case of the page title).
  9. MOVED TO 📌 Standardize how external links are wrapped with Twig trans/endtrans tags in help topics Active - When updating the User Guide links in the Additional resources section, I noticed that we aren't consistent with the {% trans %}{% endtrans %} wrapping of the link. Sometimes it wraps the anchor <code><a></a> and sometimes it doesn't. Standardizing this to wrapping the anchor tag. I don't think it hurts to give additional context to translators.
  10. PATCH - Links to the Drupal Wiki that reference "8" (i.e. "docs/8" or "Drupal 8" in the path or in the title should be updated to the current URL and page title. Only updating links and titles when there is a redirect to a page without "docs/8" and/or "Drupal 8" in the link text.
  11. PATCH - core.maintenance.html.twig: "When performing maintenance, such as installing, uninstalling, or upgrading a module" ==> upgrading should be updating
  12. OUTDATED -
  13. PATCH - shortcut.overview.html.twig: "Make sure that the core Shortcut module is enabled, " ... enabled => installed
  14. PATCH - 📌 [meta] Replace Drupal in UI text with the name of the distribution Active reminds us we should not be using the word "drupal" in UI text (including help topics). So we should check over all the topics and make sure that is the case. I know it's being used in a few topics for links to the "Drupal User Guide" (see also next item. But we will use the term "Drupal User Guide" because that is the name of the guide.
  15. PATCH - We have a lot of links to the User Guide, so part of this item is to make sure we're using a consistent link text for links to topics in the User Guide. The consistent format should not include the section number like "section 11.1" or "chapter 11", as this is subject to change as we add/rearrange topics in the User Guide.
  16. MOVED TO 📌 Add help topic about installing site from configuration Active - core.config_overview.html.twig -- alexpott wrote on #3095734-102: Convert config module hook_help() to topic(s) → (slightly edited for clarity): We need to add information about installing from configuration, as the part on cloning could encompass this. If people knew about and used installing from configuration more often then people wouldn't think so much about the site UUID.
  17. MOVED TO 📌 Clarify in the help topics that the Database Logging module should not be used for forensics Active - On #2732113: Clarify in the dblog_help that the dblog module should not be used for forensic log → they are adding a note to the dblog help about why the dblog module cannot be used as a "forensic" log. This should be added to a help topic too.
  18. FIXED in #3192585: Fix up topics to use new help_topic_link function →

    On 📌 Make a way for help topics to generate links only if they work and are accessible Fixed we added a new help_topic_link function, which allows us to make links in topics without worrying about whether the module that "owns" the linked-to topic is enabled. In topics that we created before, we did things like this:

    If you have the core Actions module installed, see the related topic "Configuring actions" for more about actions.

    We should instead use the help_topic_link function to make a topic link, so it would look like this:

    {% set action_overview = render_var(help_topic_link('action.overview')) %}
...
See {{ action_overview }} for more about actions.

    This is in quite a few topics... probably should search for the phrase "related topic" and that will find all/most of them.

📌 Task
Status

Fixed

Version

11.0 🔥

Component
Help  →

Last updated 23 days ago

No maintainer
Created by

🇺🇸United States jhodgdon Spokane, WA, USA

Live updates comments and jobs are added and updated live.
  • Usability

    Makes Drupal easier to use. Preferred over UX, D7UX, etc.

Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

contrib.social Blog FAQ Discussions
Production build 0.69.0 2024