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
- The User Guide is a good list of topics (already incorporated into the suggested outline) -- https://www.drupal.org/project/user_guide
- [to incorporate] The existing hook_help() module overviews may have some good suggestions. That text can be used verbatim.
See also #3041924: [META] Convert hook_help() module overview text to topics - [to incorporate] This post 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 - [to incorporate] Accessibility -- see comment #20
- [to incorporate] Comment #28
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]
- [U] Overview of content structure
- [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] Overview of page layouts
- [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
- Decide on the outline
- 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
- 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.
Comments
Comment #2
jhodgdonAnother 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.
Comment #3
jhodgdonSome 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)
Comment #4
jhodgdonNow 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.
Comment #5
jhodgdonComment #6
jhodgdonI'll make commits as I go...
Comment #8
jhodgdonAnother 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.
Comment #9
jhodgdonUpdating summary, with a list of suggested topics to write. May need more. Some have been done with that last commit.
Comment #10
jhodgdonRevising suggested outline, based on #2516902-2: Introduce a visual hierarchy to the help page.... somewhat anyway.
Comment #11
jhodgdonComment #12
jhodgdonComment #13
jhodgdonComment #16
jhodgdonComment #17
jhodgdonUpdating issue summary with a proposed outline.
Comment #18
jhodgdonslight revisions to proposed topic list
Comment #19
jhodgdonI 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...
Comment #20
andrewmacpherson CreditAttribution: andrewmacpherson as a volunteer and at Annertech commentedI'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:
Comment #21
andrewmacpherson CreditAttribution: andrewmacpherson as a volunteer and at Annertech commentedComment #22
jhodgdonThanks @andrewmacpherson for #20 -- great ideas!
Comment #23
kim.pepperComment #24
jhodgdonAnother 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.
Comment #25
jhodgdonHah. 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.
Comment #26
jhodgdonMoving this to Core queue as part of #3027054: Help Topics module roadmap: the path to beta and stable
Comment #27
jhodgdonUpdating 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.
Comment #28
jhodgdonI 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
Building a structured content model
Writing and editing your content
Managing visual design
Page layout and blocks (everything that's not the main content)
Planning how visitors navigate your site
Modules. Extending the functionality of Drupal
Adding note about credit to issue summary, plus some tags from the other issue.
Comment #29
jhodgdonThe 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.
Comment #30
jhodgdonAnother update:
- Changing the title
- Adding a Remaining Task to do a final review to make sure all the information from hook_help() is there
Comment #31
jhodgdonSee also this related issue.
Comment #32
jhodgdonWhoops, 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.
Comment #33
jhodgdonFix one issue link in issue summary.
Comment #34
jhodgdonAdding 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.
Comment #36
jhodgdonAdding a note that we need to think about the file name / namespace of topics when we organize them.
Comment #40
andypostIs this a blocker for stable release?
Comment #41
jhodgdonActually, 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.
Comment #42
andypostThank you! User guide mentioned in IS it totally a new feature (like help topics at install time)