Posted by jhodgdon on July 1, 2019 at 12:44pm
I'm very pleased to announce that we (hopefully) have a new help system in Core that will actually serve the needs of module, theme, and distribution developers! It is called "Help Topics", and is currently in "Experimental Module" status in Drupal core 8.8.x.
The way it works:
- Modules, themes, and distributions can have a help_topics subdirectory in their projects, where they can write help topics in the form of Twig template files. Each project can have as many topics as they want/need to document their project.
- The Twig files have meta-data (in HTML meta tags) at the top to define the title of the topic, whether the topic is "top-level" or not, and a list of other topics to mark as "related".
- When a user visits the admin/help page (assuming the Help and Help Topics modules are enabled), they will see a list of the top-level topics, and can click through to read them. When reading a topic, at the end they'll see a list of all the topics that are "related" (and "related" is automatically a bi-directional relationship).
So... The module is currently in "Experimental" status, and we need your help to get it to "Beta" and then "Stable" status in Drupal Core:
- Programmers can help with writing tests, adding features, and other tasks. Check out the "Roadmap to beta and stable" issue to find out what needs to be done.
- Documentation writers can help with writing and reviewing help topics for Drupal core (or eventually, contrib modules). Our first goal is to rewrite the existing "module overview" help as task-oriented topics -- that link is a meta-issue with instructions on how that is to be done, and a number of child issues where the work will be done. The result of that will be a set of probably disorganized and somewhat incomplete topics about how to accomplish various tasks using Drupal core modules. Then we'll need to reorganize the topics we have and most likely write a few more.
This effort is being led by andypost, Amber Himes Matz, and jhodgdon... if you have questions, we can all often be found on Slack or on drupal.org.
Comments
Drupal Slack channels to get in touch
If you have a question about Help Topics and want to get in touch in Drupal Slack (https://www.drupal.org/slack), #documentation and #contribute channels are your best bets.
My Slack username is ambermatz (jhodgdon's and andypost's are the same as their d.o. usernames).
As a best practice, if you have a Slack conversation about a Help Topics issue, after your chat, please go to the issue you were discussing and leave a comment summarizing your conversation/decision/feedback.
Thank you!
Amber Matz
Slack docs channel not documented (until now)
This would certainly explain why I never received a response on IRC in #drupal-docs...
The documentation discussion has moved to Slack without that being documented. I've now documented this at:
Thanks!
Yeah, sorry about that! The whole Drupal contribution community has pretty much moved from IRC to Slack, without much posting about it. Thanks for updating the documentation!
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
Amazing news! Thanks for the summary
That's amazing news! Thanks for briefly summarizing the very long comment thread of this Add experimental module for Help Topics issue. Hope I can find some time to prepare our GDPR module's docs in this way...
This is great, and it seems
This is great, and it seems like a logical next step from there would be power some if not all of the module documentation pages on drupal.org from this so that developers only have to manage it in one place. This would also mean that document would automatically be versioned by module version, so flipping between the 2.x and 3.x versions of the docs on d.o should be relatively simple to set up.
Interesting idea!
I'll make an issue so we can discuss that... let's see. Here's the issue:
https://www.drupal.org/project/drupalorg/issues/3066332
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon