Issue credit from other issues
Please credit these users who made helpful progress on other issues that have now been closed as duplicates:

LewisNyman
tkoleary

Problem/Motivation

On #3041924: [META] Convert hook_help() module overview text to topics and #3031642: Deprecate hook_help() and combine with Topics, we are taking the information currently in hook_help() for module overviews, and converting it to help topics. There are also a few topics in the original commit of the experimental help topics module on #2920309: Add experimental module for Help Topics.

Once all of that work is done, we need to take the information and make it into a better Help Topic outline, so that we have a help system that would actually help people learn how to use Drupal Core.

So, we need to develop a topic outline, and create child issues to write the needed help topics.

The suggested list of topics below is based partly on The User Guide project -- https://www.drupal.org/project/user_guide -- although we probably cannot take its text verbatim since it is under a different license.

Proposed resolution

Things to consider in the topic outline

Proposed Outline

Here is a proposed outline for how to group the above "things to cover" into a topic hierarchy for Drupal Core functionality. Note that the hierarchy is not unique -- some topics are listed under more than one parent. That is fine, and should be helpful for finding topics.

[W] => topic is written
[U] => topic is not yet written
[I] => topic is incomplete (partly written)
[M] => topic is written but needs to be moved somewhere in the hierarchy

  • [W] Using the administrative interface
    • [U] Overview of the administrative interface
    • [W] Accessibility features
    • [W] Contextual links
    • [W] Shortcuts
    • [W] Tours
    • [U] Installing and uninstalling modules
    • [M] Changing basic site settings
      [Note: topic covers Site name, slogan, and email address, Time zone and country, Date and time formats. Currently it is a top-level topic, and it needs to be moved here or maybe elsewhere?]
  • [U] Setting up content structure
    • [U] Overview of content structure
      [Should cover choosing between classes of content (content items/nodes, user profiles, etc.), as well as relationships between content, and have a See Also to the page design section, and to the Forms section]
    • [U] Setting up content types and fields
      [see also: entity forms topic]
    • [U] Setting up taxonomy
    • [U] Using images in content
      [see also link to the image styles topic under page design]
    • [U] Creating composite pages and blocks (views)
      [see also: display modes topic]
  • [W] Defining navigation and URLs
    • [U] Overview of internal paths and URL aliases
    • [U] Defining the site home page
    • [U] Defining pretty URLs (URL aliases)
    • [U] Setting up navigation menus
    • [W] Configuring error responses, including 403/404 pages
  • [U] Site design and layout
    • [U] Overview of page layouts
      [covers: themes, regions, responsive design, breakpoints, entity display modes, and blocks, and have a see also link to the Content Structure section]
    • [U] Creating and placing blocks
    • [U] Setting up image styles
      [see also: image topic in content structure]
    • [U] Setting up display modes for content
      [see also: text formats topic]
  • [U] Building a multilingual site
  • [U] Forms
    • [U] Configuring content editing forms
    • [U] Setting up contact forms
    • [U] Configuring the WYSIWYG editor
  • [I] Maintaining and troubleshooting your site
    [Needs to have a See Also to the security section]
    • [U] Setting up periodic tasks (Cron)
    • [U] Checking the site status
    • [W] Configuring error responses, including 403/404 pages
      [Note: topic also covers the log report]
  • [W] Making your site secure
    • [U] Configuring text formats
    • [U] Configuring roles and permissions
    • [W] Defining how user accounts are created
    • [U] Creating user accounts
    • [U] Making security updates
    • [W] Configuring error responses, including 403/404 pages

Remaining tasks

  1. Decide on the outline
  2. Write and/or reorganize the topics to fit the outline (via child issues). See also #3025577: Move help topics to core or the correct modules
  3. Before this issue is marked Fixed:
    • All of the child issues need to be fixed
    • We need to go through the hook_help() for existing modules and make sure all the information in the module overviews for currently-existing modules is covered in the topics that we've written, and that core modules that no longer exist are not referenced
    • We need to go through all the topics and review the Related relationships, and add new ones as appropriate [this could be a child issue].
    • We also need to think about file name prefixes (namespaces). If a topic is named foo.*, it will (at least eventually) be in the core/modules/foo directory (or core/themes/foo), and it will only be visible if the Foo module/theme is enabled. So, if topics are important to be visible no matter what, we need to make sure that they're in the namespace of "core" or a module like system or node or user that is pretty much always enabled, or at least one that is enabled by the Standard and Umami install profiles.

User interface changes

A great help topic outline will exist.

API changes

None.

Data model changes

None.

Release notes snippet

Comments

jhodgdon created an issue. See original summary.

jhodgdon’s picture

Another possibility for topics would be to go through the existing core hook_help() and see if there is some useful information there that we can harvest into topics. For instance, there is some help in the Field and Field UI modules that would be good, and ... who knows what else.

And by the way, we cannot actually easily use the User Guide text itself in this module (and especially if this gets into Core), as it follows the copyright/license of drupal.org docs pages (CC BY SA), so it is not GPL or GPL-compatible. However, since that whole project is under CC BY SA (by permission of the Licensing Working Group), we could conceivably make a contrib module as part of that project that had some or all of the text of those topics as configurable help. Anyway... we can at least look at the User Guide for ideas about an outline... although probably many of the Task topics in the User Guide would be better as Tours than as Help Topics. I think Help Topics are probably better for overviews and pointing you towards how/where to do things, rather than as step-by-step instructions, since at least right now they don't have images. And hopefully the UI of Drupal is good enough that if you get to the right page, and understand the concepts and background, you can do what you want to do... Well, we can see.

jhodgdon’s picture

Some ideas of topics (or groups of topics) that would probably be useful... grouped by (maybe) what a user would think about, rather than by module that takes care of that functionality (in no particular order):

a) Glossary/terminology
b) Cron
c) Themes, responsive themes, regions, breakpoints, site layout, blocks, custom blocks
d) Contextual links and how to use them
e) Content entities and fields (including what types exist, what is the best use for each one, etc.)
f) Navigation, menus, custom URLs (aliases)
g) Forms (content editing forms, contact forms)
h) Building a multilingual site
i) Security (text formats, roles, permissions, user account settings, keeping track of security updates)

jhodgdon’s picture

Now that #2688730: Add new item button is not working due to serialization problem and #2687787: Provide a method for locking topics against editing are taken care of, I'm going to actually write some of these topics. I'll be using text from the existing hook_help() for Core modules, and working on the list in comment #3.

jhodgdon’s picture

Assigned: Unassigned » jhodgdon
jhodgdon’s picture

I'll make commits as I go...

  • jhodgdon committed 74e7531 on 8.x-1.x
    Issue #2687107 by jhodgdon: Write some core help topics and edit the...
jhodgdon’s picture

Another couple of topics to write:
- Shortcuts (add to UI section I already started)
- Tours (also in UI)

Another idea would be to take out the module dependencies for most of the topics, so that they can be viewed whether or not you have the module enabled.

jhodgdon’s picture

Issue summary: View changes

Updating summary, with a list of suggested topics to write. May need more. Some have been done with that last commit.

jhodgdon’s picture

Issue summary: View changes

Revising suggested outline, based on #2516902-2: Introduce a visual hierarchy to the help page.... somewhat anyway.

jhodgdon’s picture

Issue summary: View changes
jhodgdon’s picture

Issue summary: View changes
jhodgdon’s picture

Issue summary: View changes

  • jhodgdon committed 6256f60 on 8.x-1.x
    Issue #2687107 by jhodgdon: Write some core help topics
    
  • jhodgdon committed fe8272d on 8.x-1.x
    Issue #2687107 by jhodgdon: Write and edit more core help topics
    

  • jhodgdon committed 9e532a1 on 8.x-1.x
    Issue #2687107 by jhodgdon: Write more core help topics
    
jhodgdon’s picture

Issue summary: View changes
jhodgdon’s picture

Issue summary: View changes

Updating issue summary with a proposed outline.

jhodgdon’s picture

Issue summary: View changes

slight revisions to proposed topic list

jhodgdon’s picture

I recently learned of this post, which is about the conceptual difficulties new Drupal users have. We should make sure we are addressing these issues in the help topics (as well as the User Guide):
http://yoroy.com/pieces/drupal-ux-conceptual-criticals
I haven't gone through the post in detail yet to make sure we have it covered...

andrewmacpherson’s picture

I've been thinking about how to organize the accessibility help topics. We could organize it along the lines of ATAG 2.0, and provide accessibility help sections corresponding broadly with Parts A and B.

ATAG Part A - "Make the authoring tool user interface accessible". This is what we already have here in the "Using the administrative interface > Accessibility features". We can describe the behaviour of various UI components, particularly Drupal-specific ones, along with notes about how they work with various assistive tech. In particular, this is about implementing ATAG Guideline A.4.2: "(For the authoring tool user interface) Document the user interface, including all accessibility features."

ATAG Part B - "Support the production of accessible content". We don't have this yet in the plan here. We can provide advice about various Drupal features which help authors to produce accessible content. I'm not sure if this would be best as a high-level topic, or split among the various sections already listed here. In particular, this is about implementing ATAG Guideline B.4.2: "Ensure that documentation promotes the production of accessible content."

Some questions, because I'm not sure I understand the architecture yet:

  1. Can a topic be displayed (in full) on more than one than one page? I think that's intended, but I want to check. Or, do they only appear in full on one page, but appear as "related" links on multiple pages?
    • Use case: CKEditor module has a custom toolbar configuration UI, which deserves some accessibility help. This would need to be available under the CKEditor module help page, AND the "Using the administrative interface > Accessibility features" page. Could it be displayed in full on both pages? If not, how do we decide whether the full text should be alongside the module help, or in the UI accessibility section (ATAG part A)?
    • Use case: Image module would provide help about how to configure and use the alt attribute. This would be equally relevant on the Image module's help page, and the "Creating accessible content" section (ATAG part B).
  2. Do all attached/related topics go into one group on their host page, or can they be organized into groups/headings on the host page.
    • Use case: some a11y topics could live under a "known accessibility problems" heading on the "Using the administrative interface > Accessibility features" page.
andrewmacpherson’s picture

Issue tags: +Accessibility, +atag
jhodgdon’s picture

Thanks @andrewmacpherson for #20 -- great ideas!

kim.pepper’s picture

Issue tags: +DrupalSouth 2018
jhodgdon’s picture

Another thing we should think about, before I forget:

Each topic can either go into the main help_topics module (which will probably be merged into the help module at some point), or it can go into another module. I think we can be strategic about that.

For instance, we might put an overview of what Views can do into the main module help, so it's visible even if the Views UI module isn't visible, and it would note that you need the Views UI module enabled in order to create/edit views in the admin UI. And then if we write some task topics about the specifics of how to create views, we would put those topics in the Views UI module. Similarly for Field UI.

This way, people can learn about the modules that they would need to enable to do a particular task, without already having those modules enabled, but not get task topics that they can't execute until the required modules are enabled.

Does that make sense?

We need to put the ideas from #20 and this idea into the issue summary at some point, when they are ready.

jhodgdon’s picture

Hah. I was just going to update this issue with essentially what is in #24, because it came up again on #2920309: Add experimental module for Help Topics.

jhodgdon’s picture

Title: Write some core help topics » Write more core help topics
Project: Configurable Help » Drupal core
Version: » 8.8.x-dev
Component: Documentation » help.module
jhodgdon’s picture

Updating issue summary... Looks like comments 19, 20, and 24 had not been addressed in the summary.

#24 is actually a separate issue now: #3025577: Move help topics to core or the correct modules

Added the other two to the summary as additional things to think about before we finalize the list of topics to create.

jhodgdon’s picture

I just closed #2516902: Introduce a visual hierarchy to the help page. as a duplicate of this issue, because it's about creating a good hierarchy of help topics.

The outline suggested by @tkoleary there is:

Getting started with a new site

  • Getting around the administration pages
  • Setting basic global configuration

Building a structured content model

  • Content types and how to build them
  • Using relationships to link related content
  • Using Display Modes to show content differently for different pages

Writing and editing your content

  • Configuring the WYSIWYG editor
  • Adding and editing content
  • Managing publishing settings
  • Using the content list page to browse and bulk edit

Managing visual design

  • Themes and how to install them
  • Working with images and media

Page layout and blocks (everything that's not the main content)

  • Where blocks come from and how to make them
  • Placing blocks in a layout and setting visibility

Planning how visitors navigate your site

  • Menus, how to create arrange and add links
  • Taxonomy, creating categories to organize content

Modules. Extending the functionality of Drupal

  • Finding modules
  • Installing modules and dependencies
  • Removing unneeded modules

Adding note about credit to issue summary, plus some tags from the other issue.

jhodgdon’s picture

Issue summary: View changes

The issue summary here is confusing. I'm going to remove the "Things to cover" list from the summary, since that is not the proposed outline and it seems confusing to have 2 things in there that look like outlines.

jhodgdon’s picture

Title: Write more core help topics » Reorganize topics into sensible outline, and/or write more topics
Issue summary: View changes
Related issues: +#3041924: [META] Convert hook_help() module overview text to topics

Another update:
- Changing the title
- Adding a Remaining Task to do a final review to make sure all the information from hook_help() is there

jhodgdon’s picture

Related issues:

See also this related issue.

jhodgdon’s picture

Issue summary: View changes
Related issues:

Whoops, that didn't work. Adding #3025577: Move help topics to core or the correct modules to the issue summary. It was already marked as Related.

jhodgdon’s picture

Issue summary: View changes

Fix one issue link in issue summary.

jhodgdon’s picture

Issue summary: View changes

Adding another To Do to this issue, which is that as part of this issue we should review all the topics and see if they have enough Related topics on them. Because as we are creating the topics, sometimes we might be writing topic A before topic B and the relationship doesn't get created because it doesn't exist at the time.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.0-alpha1 will be released the week of October 14th, 2019, which means new developments and disruptive changes should now be targeted against the 8.9.x-dev branch. (Any changes to 8.9.x will also be committed to 9.0.x in preparation for Drupal 9’s release, but some changes like significant feature additions will be deferred to 9.1.x.). For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

jhodgdon’s picture

Issue summary: View changes

Adding a note that we need to think about the file name / namespace of topics when we organize them.

Version: 8.9.x-dev » 9.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

andypost’s picture

Is this a blocker for stable release?

jhodgdon’s picture

Status: Active » Closed (outdated)

Actually, my opinion is that we should close it as Outdated. I think the way we did the individual Topic issues, we have a pretty comprehensive list of topics with good cross-linking.

If someone disagrees we can reopen this, but I think we will be good to go once we have the final remaining topic issues committed.

andypost’s picture

Thank you! User guide mentioned in IS it totally a new feature (like help topics at install time)