 Hi everybody and welcome to this core conversation, a new help system for Drupal. In this session I'll be presenting about an issue in the Drupal core ideas queue that proposes that a sandbox project called help topics be committed as an experimental module. The conversation will hopefully center around the validity of the requirements I present and the proposed solution and my goal today is for us to ascertain whether this issue should be marked as RTPC reviewed by the community and move forward for review by a release manager. At present this plan has been signed off by a product manager and framework manager and is awaiting sign off by a release manager just to give you an idea of where we're at right now. My name is Amber Himes Matz. I'm a production manager and trainer at DrupalizeMe and you can find me on Twitter at Amber Himes Matz. My Drupal.org username is also Amber Himes Matz. I want to say a special thank you to Jennifer Hodgson. She is the creator of this help topic sandbox and is the champion of this proposed plan. She is mentoring me as a new maintainer and I just want to thank her for that. Also I want to say a special thank you to Andy Post who has been contributing code and reviews to this help topics project. The issue in question is in the Drupal core ideas queue as I mentioned and is titled meta help system overhaul and that's at Drupal.org slash project slash ideas slash issues slash 259-2487. I'm going to be reading off a lot of issue numbers today because there are a lot of a lot of people thinking about the help system and a lot of ideas have been floating around and this is by no means the first time this has been brought up. So why this proposal improving documentation is a shared concern and one aspect of Drupal's documentation is its help system. Usability testing on the admin slash help page on a Drupal site exposes some problems with the current help system. I want to clarify that I'm talking about Drupal's in site help system where you go when you install Drupal, you have a Drupal site and you click on that help button in the admin menu. So that's what we're talking about today. We're not talking about Drupal.org documentation. That's also an excellent discussion but it's not what I'm going to be talking about today. So why are we proposing this solution in core instead of in a contributed module? One reason is that it would provide an official way for contrib maintainers to provide better help for modules, themes and profiles. Also better help can be provided for core for its own modules, themes and profiles. Since this help is within the site, we also want to empower site builders to provide specific help pertaining to their site's configuration for their own custom workflows and processes. Drupal is for customization. There are many custom workflows. People do things their own way. They have their own content types, their own editorial workflows. Why shouldn't they have be empowered to provide in-site help for their own custom workflows? In the configuration system world, there's a mantra that sites own their configuration. Once you import it in, you own that config. I say that site should also be able to own the help that describes how to use their site's configuration. That help should be provided as near to the site as possible. There's hardly a place near than within the site itself. What is better help? What do I mean by that? I'm specifically referring to one best practice of separating help documents or topics into a single concept or task. Better help is also as close to the product as possible. That's why we have help text for fields, for example. But specifically here, I'm talking about help that you can find via admin slash help or the help menu item in the admin toolbar as opposed to help on Drupal.org or elsewhere. Better help is also maintainable. If a feature is not documented, it might as well not exist. So many workflows are custom to a site and blindly clicking around at admin screens is a rapid path to frustration. And here, stakeholders, I mean maintainers of modules, themes, and profiles who want to ensure that their projects users have a positive experience as well as specific site stakeholders such as site builders, administrators, owners, or other kinds of site and content maintainers who either want to provide help to their team or who will use the help system. The current system, as you may know, is powered by implementations of hook help and it hasn't changed much since Drupal 4.6. Only modules can implement hook help. By implementing this hook, your module can provide a module overview, a link which appears on the main help page at admin slash help, or it can provide page specific help. The page specific help information appears in a help block provided by the core help module if the block is displayed on that page. Out of the scope of today's discussion is the tour module which also appears at admin slash help and that's another issue for another day. So what are the limitations of the current help system and what are some desirable features of a new system? I'm going to present the limitations and desired features of a new help system in three broad categories. Finding help using Drupal's help system, the technical implementation, which really does impact the final category, the help offering experience. And then I have some questions at the end to kick off a discussion. The first limitation is that help is not organized in a topical manner. You can't find help by topic or by your goal only by the name of the module. On the admin help page, module overviews are organized by module alphabetically. Here's an example of a list of module overviews. This list only overviews for the installed modules on your site. If you wanted to know how to configure the editing buttons that appear with the body field on a content editing page, you would need to know that the module that provides that functionality is called CK editor. Presented with this page and assuming you start at the top of the list, you would first read about automated cron, big pipe, block, and breakpoint before getting to CK editor and discovering that this is the module you need to learn about. The current system requires that you know what each module does to find help for its functionality. Why should I care about which module provides the functionality? I just want to accomplish a task or understand a certain concept so that I can get on with my work. Also, each module can only provide one module overview on the administrative help page. This is actually not such a bad thing when we're talking about module overviews per se. But what I want to focus on is the limit of one page. What we want is to extend the help system's usefulness so that modules and others can provide multiple pages of help beyond just a module overview. What we want is to provide a way to organize help by topics, not just an alphabetical list of module names. In order to organize help by topics, we need help topic pages. Right now we just have module overviews and what we want is to provide modules, themes, and profiles with an ability to provide multiple help topics with a recommendation that each help topic page is either a concept or task. A concept help topic conveys something a user should know and a task help topic provides step by step instructions for something a user needs to do. Since we would provide this ability for projects to author multiple help topics, we don't want to overrun the main help page with all of these many topic pages. So we also need an ability to have at least a minimal amount of hierarchy or the ability to organize help topics by sections. One way we're currently solving this in the proposed plan is to list only topics marked as top level on the main help page. Another way is by using fields in the relationships and hierarchy fields set in the help topics entity and more on that later. There is already an issue open related to organizing help hierarchically and that's issue 251-6902 introduce visual hierarchy to the help page which you can look up if you like and contribute to that conversation. Also on the subject of finding help, a limitation of the current system is that there is no way to search help and so it would be great if a new help system provided a way to search help. Some questions related to this desired feature include should this search results extend to all administrative pages? Should it include non-installed modules themes or profiles? As you will discover if you've tried out the patch for this issue for help topics, at the moment we don't include a search functionality. Jay Hodgson, the author of the sandbox project, proposes that this feature could be added during the beta phase after the experimental module is committed and before its full release. Basically we don't want to put the work into it if it's going nowhere it's just going to sit in the issue queue. The issue for help topics specifically to add search capability is 2664830. Also it's worth mentioning a related issue 102254 add an administrative search feature which proposes to add search for both the all of the administrative help pages not just help. A nice to have feature related to finding help would be a glossary especially a single extensible glossary that could be added to by any module or theme and someone's already thought of this as well and that's issue 2701289 a glossary to extend the help system and that idea is being discussed there. Next as already mentioned there is this limitation that a module must be enabled in order to see its help page. So again you must know what a module does before learning how to use it. For example responsive image module is not enabled by default but image is and image module provides image styles so you wouldn't know that there's this possibility that you could configure image or responsive images unless you enabled the module. Wouldn't it be nice to be able to read about responsive image module before you actually install it? It's a little more difficult now with Drupal H2 just disable a module. The checkbox goes immediately disabled as soon as you install it and it kind of begs the question well I just wanted to read about this help on this page. How do I now uninstall this module? So a desired feature would be able to read about the module before installing it. I'm not going to dwell too much on this feature in this presentation especially at this time we're not solving it with our proposal. However this is definitely something that has come up in the issue queue and it's there's a related issue 2587469 allow hook help to run on modules which are not enabled. Also if this is a limitation that seems really important and we're not really giving it as much importance as you think it should let's bring it up in the discussion at the end. One of the most cited issues with hook help is its code but what are the specific limitations and what would be some desirable improvements here? The first limitation is that there is markup for help in a PHP file. Markup for help information is provided by this PHP function hook help by concatenating translatable strings with html tags and returning the output like this. Yeah but it's serving some purpose one of the things that help information needs is some structure it needs some semantic markup such as headings and paragraphs and lists etc. Secondly if you look carefully here you can see that it's chunking the help information as a whole into short translatable strings as you can see with the many different t function wrappers in this example. So those are both essential functionality to retain in any new system. Some folks do object to having any markup whatsoever outside the theme but help pages are pros and need semantic markup like headings paragraphs lists etc not unlike body fields and content. I completely realize that there is a whole debate about what should or shouldn't go into a body field but what we are arguing for is that help topics do need a limited but essential set of html tags to provide it to provide needed structure. How that markup is provided is up for discussion but right now we're talking about the markup in this PHP file. One of the difficulties that arise from having this markup here is that it makes it difficult to write help if you're not a programmer or if you don't have access to that file when we'll get to the authoring experience shortly. One essential feature with regard to whatever markup solution is ultimately brought to bear is the need for short strings for translatability sake. The reason for that is that a translation file is invalidated if anything is changed and if that translation string is a whole article then it just makes it that much more difficult for the translator to update that translation for QA to happen on it as well. It's just much easier to translate short strings of text and to sit down like okay I'm a translator I've got 15 minutes to work on this I'm going to translate a few short strings here and move on you know with what I can do now. Otherwise they have to sit down for several hours and go through an entire article that might have like m tags or strong tags interpolated into it typos happen it's just much more difficult to translate a large chunk of text and that's why we're really focused on this also if it's a core project this is essential. So we have this desire to have a more appropriate place for markup a place that is not a PHP file for starters. One proposed solution has help topics ultimately saved as config entities in YAML files for distribution. This solves markup not in a PHP file it also enables a means of distribution for modules themes and profiles who can provide help topics for their module theme or profile in config slash install or config slash optional. So the author would write the help topic using an administrative form that has a title and a body field with a limited set of HTML tags provided by text format and some other fields as well which I'll show you in a minute. When the form is submitted the module behind the scenes breaks up the chunks of HTML entered into the body field and organizes those chunks into a YAML list with a chunk no larger than a paragraph. So the markup is still chunked into small strings for translation and wrapper tags are values in prefix tags and suffix tags keys which addresses the issue of short strings for translatability. Additional values in the help topic entities such as related links and dependencies are also saved within the config entity. However in the text if there is inline markup that will appear in that text value key. So it's not a total purist solution but it does do some things very well. There has been quite a bit of discussion in our issue queue about how help topics should be stored and where the markup should go. Alternative solutions include using the plugin system markdown or twig files or some combination thereof or something like what paragraphs module provides. These alternatives may or may not fulfill the desired feature but the main thing is there's no patch so what we're trying to do is move something forward make an improvement to the system we have a solution ready there is a patch that's ready just you know all but ready and it's you know let's move forward with it. Also it's been existing for quite a number of years now too. Here are some of the places where you can find the discussion about these alternatives that specifically address the problem of markup and help. One of them is 218-8753 get rid of hard coded markup and hook help implementations. It's not to the point of a patch yet. Another is a postponed issue 191-8856 put each module's help into a separate twig file. Probably the most cited alternative is 2820166 a flexible plugin based help system which also proposes to put topics in twig files and the main question we have for this solution is does it improve the authoring experience what about twig file access and what about translatability certainly there's the trans tag in twig how is that going to work out for the help authoring experience what about a markdown based solution is this really better than html and more critically what about short strings for translatability finally what about something like the paragraph module where instead of authors using any markup whatever they enter content into specific fields you would select the type of markup entity you want such as a paragraph or a heading or an unordered list and then each list item and you enter the content for that particular markup entity into each field so let me tell you it makes for quite a tedious authoring experience in fact the first iteration of help topics used that solution and it was coined paragraphs light and the discussion when we brought it to the the UX team for review was do we really want to basically bring paragraphs into core you know a paragraphs light solution into core also the the form and the the authoring experience was quite arduous and kind of clunky and it was ultimately rejected by the UX team and that's why it was refactored to use that single body field with the chunking into short strings happening behind the scenes by the module so that's why that decision was made so it was considered definitely and it was the first iteration of it the next limitation related to hook helps technical implementation is its code module overviews are created by responding to a fake route which is weird hooks are still in use but considered outdated and pages are now generated by controllers plugins or yaml files the admin slash help page does now allow other help providers such as the tour module to list their whatever it is on the help page so that's not really a limitation but an opportunity in our proposal we are not suggesting that hook help be deprecated why module overviews still have a place and a purpose many modules many use hook help for this purpose our proposed plan we feel is complementary to hook help not a wholesale replacement hook helps code is useful for several purposes first it allows logic because it's php this is useful for checking to see if a module is enabled before displaying a link for example and other complicated or less straightforward use cases can also use the logic there's always an edge case right these edge cases might be partially solved by our help topics project but really we're not interested in this point at in a wholesale replacement of hook help what we want is to prioritize the the problem of providing better help through the provision of concept and task help topics within a Drupal site that's what we're focused on finally a major consideration for us is the authoring experience Jennifer and I are both programmers and we're technical writers we empathize with both audiences but we really do not want to neglect the author of help in fact we want to empower them i think it's fair to characterize the help authoring system uh the help authoring experience as poor the current hook help syntax may be difficult for documentation writers who are not also php programmers i mean it's even a bit tricky for php programmers how many times have you not been able to see that you forgot that little dot concatenation error and that's why your page is white screening there is currently no way for a site builder to add pages to the help system for their own site except to create a custom module with a hook help implementation even with hook help sites builders could not create a set of help pages tailored to their site because of the limitation of one help page per module unless they created multiple modules with their new module development powers each with a hook help implementation or if they used a contributed module such as advanced help ultimately the authoring experience is impacted by the issue of finding a more appropriate place for markup and whatever the solution is to that problem should have a positive impact for the authoring experience so a big part of the the solution we're proposing includes providing an admin ui to enter help topics with the goal of improving the help authoring experience just providing a ui isn't enough to improve the authoring experience we all know that ui's vary wildly in their usability and effectiveness so we set out to provide a simple ui that is familiar and easy to learn the main text of the help topic is written into a single body field there are other fields available to indicate relationships to other help topics and hierarchy and more on that in a moment also you can indicate module or theme dependencies which is very useful for module and theme developers who want to package and distribute their help topics in that in the body field tokens are available for internal page routes or links to other topics and that just as a quick aside is the remaining kind of blocker issue that we're working on we discovered that the xss filter for those tokens is a bit aggressive and it's stripping out some of the essential characters of those tokens so that's kind of the final piece the problem of short strings is still handled behind the scenes by the module instead of by the author which would be the case like in a paragraphs module implementation the author would be responsible for for chunking that data the author can write the topic as they would write any other article for a web page without being waylaid by tedious data entry into multiple fields for the main text of the topic this UI has been reviewed by the core UX and usability team and approved by providing this UI we can make it easier for a non coder to contribute help topics help topics also provide some permissions roles can be granted to add edit or unlock help topics yes help topics can be locked for read only because the help topics are ultimately saved as config entities and dependencies on modules or themes can be indicated the topics can be deployed to other site instances through the configuration system meaning help topics could be written on a local site and deployed to a qa instance before launch of a live site for example have you ever been in a situation where you're developing a site for a client and part of the contract is you need to write some help for them and you're using the the help system maybe we're using advanced help for example and it's this but if you were using a database system like a form like okay so are we exporting this development database to prod no you know like what how do we actually deploy the documentation that we're providing for the the client so by using config entities it actually provides a nice vehicle for distribution to other instances of the site so not just for module and theme developers who want to provide some help topics but also for for vendors and agencies to provide help for their clients one of the limitations that this admin UI also seeks to address is that there is no great way to cross link to other help currently this is done with php code so you would in php you would check to see if a module is enabled and then you would use special fancy placeholders the syntax for that is always just a little bit tricky you're always like copying and pasting very carefully and and just it's a it's a very careful tds process to do that i mean it's totally possible it happens all the time there's plenty of good examples certainly this is a thing that that php developers do all the time but for a non programmer this is a little bit intimidating so a desired feature would be to provide a more straightforward way to cross link to other help topics right like content types relationships fields references this is a part of the Drupal way so why not provide that in the admin UI so part of our proposed resolution is to provide a way to either list related topics or to indicate topics to list this topic on this is going to be a bit of a mouthful explaining this so if we look at this UI here we've got two options we've got topics to list here and so for related topics if topic a list topic b and related topics then someone viewing topic a we'll see a link to topic b in the related topic section at the bottom okay for the second option if topic a list topic b and the topics to list this topic on then someone viewing topic b will see a link to topic a in the related topic section at the bottom you might already see how this could be useful so you could use either of these fields to make links between topics in general the first one related topics is preferred however you might want to use topics to list this topic on instead if you're creating custom topics for your site and the topic you want to link to to appear on was provided by a module you might want to avoid editing the module provided topic for easier updates another scenario would be that you were the module developer and are writing topics to provide as part of your module and the topic you want to link to is not part of your module so you can't edit it or it has more module dependencies so it might not be present on a given site so this helps to augment other help topics provided by other providers get you know still retaining like is the module enabled what are the dependencies and such like that without needing to edit these other providers one of the objections that has been raised is a module developer writes help topics and they don't want to be fielding questions in their issue queue about edits to their help topics because they that link to some another help topic or something like that well you can just use these fields to link to the related topic without the need to edit that one okay so let me summarize the requirements as I've identified them help text needs semantic markup it's desirable to have minimal or no markup html that is outside of a theme and help topics should be chunked into short strings for easy easier translation also help topics need to be distributable with modules themes and profiles and these help topics distributed with modules et cetera sometimes need to be updated finally help authoring needs a ui that is familiar and usable to non programmers also help topics need to be authorable by site builders and by site builders I'm meaning that very broadly like anyone who can administer the site so let me sum up our proposed resolution our proposed resolution would keep hook help in place but add a new system alongside it that would coexist using config entities for help topics and a ui for authoring help topics would be saved as config entities the same as tours do this method makes updating a bit more difficult and as pointed out in issue q discussions some markup is outside the theme although the individual components of a help topic such as the text wrapper and the related topics remain themable so it's themable in the same way as a regular node the different the and the similarity is that a body field that allows markup in a node is the same level of themability as a body text in a help topic with the added feature that the text format provided by the help topics module or the recommendation would be to only allow limited and restricted text formats for the help topic each module theme or profile can provide multiple topics by authoring topics using the ui and exporting configuration into yaml files and placing them in either config slash install or config slash optional only topics marked as top level a config property and a field in the ui are listed on the main help page at admin slash help site builders can create more topics and organize them in a hierarchy by indicating top level and by using that those relationships fields non-programmers can author and contribute help topics by using the ui and exporting the configuration into yaml files using the configuration manager ui short strings for translation are saved in the translatable config entity and i should have mentioned that before the one of the benefits of using a config entity is that it's it's translatable and it's saved until no longer no larger than paragraph size chunks so let me exit out of this and show what this looks like so here is the main uh help page here's the module overviews and right now here's where some configured topics uh jennifer's written some help topics just to be able to demonstrate this module so you can see they're listed here only the ones that are marked as top level are listed on the main help page there's also a help topics listing page this is like the the administrators page for help topics so you can add a new help topic you can see all the ones that are listed certainly this list could be improved if if there if it if this becomes like a really popular thing and becomes accepted in the core maybe it needs to be organized in a different way um so but right now it's a list here you can see the machine name which is useful for providing the related uh topic links um or a route uh in a token you can see if it's marked as top level or if it's locked and you can view the operations my user account has full permissions to do all of these things so you can um unlock I also have translation uh modules turned on because I was testing the translation interface with these and so there's some extra things here like translate the um add a help topic form has a title this is an extra block because of the translation modules I have enabled and then here's the body field there are some this help text format is provided with the module um and you can see we've got some text formats here so you could have uh use permissions and text formats to to add or restrict the text formats that are available for editing and adding help this is a very familiar interface it's just using ck editor as well so it's a very familiar interface for just about anyone and it's easy to learn if it's new and then here are the relationships and hierarchy and these topics and the list this topic on both um are comma separated lists of machine names so you can see the machine names in that that list and you can um indicate them here also for modules module and theme developers you can add module and theme dependencies if you are a module developer you're probably at least a little bit uh familiar with the configuration system and the ability to add dependencies to your module so that's where you would do that here um in the edit form you can see the machine name and the title um this is just an example of how you can do formatting so this is just an example of it filled out and then here's how it appears and when you're viewing a help topic uh we have this standard uh we have help for the help topics and so this will take you back to the main help page or the help topics administration page uh where you can get back in and add new ones or see sequence and so here's the related topics so this when i say that it's still themeable i mean like these chunks here are themeable and then this is what is appearing in the the body field and this is just another example of a help topic and here is an example of the configuration uh export so this is a config entity it's in yaml and you can see here where uh some of the values for specific to the help topic top level if it's locked here's the related list on these are just yaml lists and then here's how the markup gets chunked out so here you can see there are some markup tags that are inline interpolated i don't have the token here because of that issue i was telling you about um and then the prefix and suffix tags for the wrapper for the for the individual chunk so it's um so you can see how um how it how the markup is saved in this configuration entity there have been uh there are a lot of related proposals a lot of people have been thinking about this problem of improving help for a long time and i just want to mention some of the other proposals that are in various issue cues um just to note these other proposals listed here are not part of this uh core ideas plan improving help has definitely been on the minds of many Drupal community members and there are many great ideas for how to improvement how to improve it mostly i am recommending our system because it's well developed and it's closest to being ready to commit so the first one is uh use an approach like Drupal 7's advanced help for the help module this module provides uh so the idea would be the module provides help topics in html format with a hierarchy file it resolves some of the issues and limitations that i brought up here today it does break the many strings for translatable translatability desired feature uh the second other proposal is replace hook help with a help plugin uh this is a kind of a recurring idea it proposes to resolve code that that code issue with hook help by replacing it with a help plugin system the plugins could be topics with titles instead of module level pages another proposal is to put each module's help into a separate twig file it might resolve the code and authoring issues too um authoring a twig file it it really varies in usability it just depends um it it depends really it could resolve the translatable translatability uh issue if it's done carefully another proposal is to get rid of hard coded markup in hook help it proposes several ideas to resolve the markup and authoring issues and it's just simply not to the point of a patch yet probably the most cited um alternative in our issue queue is uh 2820166 flexible plugin based help system it proposes to use the plugin system and put topics into twig files does this improve the authoring experience that's what i'm always going back to so i'm thinking i'm imagining um i've i've downloaded a module i'm i'm browsing through the code even just you know as a someone who is competent enough to like browse the file system i've got assuming i've got access to it even and and i'm looking for where the module is providing um the help files when i see a twig file am i thinking this is where i'm going to find help topics or am i thinking this is where i'm going to find templates that i can theme um so i'm not sure um i don't know if there there's an argument to be made there um i'd be willing to listen to anyone who is really um on fire about about this uh proposal and it's certainly been a point of discussion in our issue q another idea that's been floated around is help topic is as content entities i think the statement is something like this should really be content entities and yeah maybe it should be but uh distribution as i understand it of content entities is a bit difficult slash impossible i'm not really even sure um if you have some insight on that um i'd love to hear about it um some some markup is is outside the theme even so with this uh solution okay so i've presented a bunch of information about the limitations and some ideas for improving the system um are there features or limitations that we've identified that are just not important or we shouldn't try to solve with the system are there additional features or limitations we should try to solve um that's just to kick off the discussion if you have other questions or concerns or points of discussion uh let's kick it off benji hi thanks for all the work on this um i i've looked at this before and i i think you've convinced me that a site builder who typically is someone like me working at an agency building a site for a client a site builder um needs assistant ad help to a site also the site administrator my client who's going to be living with that site going forward that administrator needs a way to add help and and these audiences need an easy way to add help we we need an admin ui and although it's kind of weird to have it in configuration i think you've explained why it can't be content and for these two audiences um we don't want it to be in files in the file system so config seems like like what the choice we have left to us um one thing i don't understand is why we don't create a separate system for those two audiences create a separate system for site builders and site admins that looks a lot like this um and then let modules and themes and profiles um continue using hook help um maybe there should be some improvements to hook help like i think it's crazy that hook help produces a single string rather than a render array but that's another question um why not have the two separate systems um why do you think that this system should also be used uh by modules themes and profiles i think um my my answer to that question would be because it can i think it was initially what who the initial audience that was thought of was the modules themes and profile excuse me maintainers so the initial objective was right now only uh only module developers only modules can implement hook help so first let's extend that ability to provide help to themes and profiles there are some really complicated themes out there and they they have documentation on dripple.org a lot of them do um but at least giving them the opportunity to provide help is is very useful um profiles for similar reasons a lot of things are hiding away in profiles and there's a lot of gotchas when you install a profile um you're like why can't i find this oh it's in the profile right um so there's a there's a benefit there to the community by extending that to themes and profiles because of the the ui i saw an opportunity there um i'm like hey it's a ui um you can use this whoever you are you can use this to write your help topics in an easier fashion and you export it to your config industry and save it to your module and you can distribute it that way also you can a site builder can you know do that equally as well there may be not distributing it as a module but it's saved to the database they can access it um through the system so it to me it provided this additional opportunity and i think it's just it's so um important that we empower site administrators and they own their site they get this custom site delivered to them if they don't if they're not able to maintain their help system um it just makes it so much harder to onboard new people to you know to train their staff why not empower them like they're it's their site why not allow them to provide better help by being able to write an in-site help system without needing access to the file system so to me the initial objective was to extend the ability to provide better help to modules themes and profiles but this opened a door to be able to empower site administrators as well and now i think it's really important so thank you i'm grant i have been looking for something that lets um my site owners uh add help and so if they're on a page and it's one particular kind of content they'd really like to be able to add help about that page or it could be a layout page full of paragraphs full of views and whatnot so uh custom help for them that is contextual to where they are the ability to add it from where they are and the ability to view it from where they are and they kind of hate clicking on a help button that takes them to another page and then they have to come back so having something that's visible in a sidebar which i did for them in the previous triple site but i haven't yet done for them here but they are used like a theme layer and blocks and it was a pain in the butt but i saw a module called the uh i think it's called moderation notes it's brand new it depends on a new JavaScript library that came with 8.5 so brand brand new that uh handle sidebars and i was just wondering if things like that are on the radio because you know the contextual stuff and the ability not to have to go some way to see that i think that that has that is an excellent point and um anyone else just by a show of hands would you find that sort of thing useful so i think it's something that's been uh brought up but not really strongly considered so we're definitely going to take a look at that i think that it's it's definitely it's possible right because we as a module developer we can retrieve that configuration um quite easily and so it's definitely possible to develop a solution where that that could be a thing so i'll definitely bring that back um for consideration i think that that is an excellent point thank you grant i saw you have the the ability to have like some of the topics be top level yeah but is there actually any hierarchy below that like two three levels and also ordering of the topics like when they're at the top level which one is the first so we have something like weight we have in taxonomy terms or something like that i think that um i think that the related topics are ordered by the list um how you have them oops how you have them listed and but to answer your question directly no there isn't any further hierarchy so right at this point like this is like a proof of concept like let's get this into core and then let's develop you know let's listen to the community again and and see you know what other i think there's definitely going to be a need to organize by section more you know more explicitly and to provide additional hierarchy there's definitely going to be a need for that on even the administrative page so right now no um but we'll definitely yeah consider it i think it's going to be obvious that it's going to be a need once this gets adopted right now like in the example there's like i don't know half a dozen help topics our plan is if this gets accepted into core as an experimental module then jennifer and i who also coordinated an effort along with joe over here to the user guide authoring so we would mount an effort organize an effort to write more help topics for the core module and it would become like very obvious at that point that we need some way of organizing it so i imagine that technical features would be added at that point that would be my best guess wondering if there's been any thought put into instead of sort of having all this help you know at one central page and all of its sub pages uh having it more contextual so for instance being able to edit the help text that appears on the node add page where you're choosing which content type to add you know giving somebody more hints about what they might want to do in terms of adding a content type do you mean something more than what is already provided by like a content type where you can provide some help for the content type and for each field and the reason is that sometimes you might have a content type which is created as part of a module and that help field isn't something you can normally edit without you know doing it in php or you know some sort of an alter hook but if you were able to when you're setting up a site as an administrator sort of add content to pages like that that are local changes and not and don't have to be committed as part of a module i think that would be very helpful i think um so i want to just clarify your your idea so i think that maybe someone else can help me out here but i think that there is a way to have help that you can edit in when you're editing the content type i think there's a way to add help with that ui there there is but if it's being provided if that is generated as part of the if that content type is created by the module itself you wouldn't necessarily want to edit that because you would be because if they were that module is ever updated it would revert your changes it's it's part you know that's part of the config that's included with the module okay does anyone else have any and that's just one example i think there might be other places where for any given route uh you might want to be able to add help text and right now you can do that through the current help module with the help block so you could configure blocks to appear on certain certain pages perhaps and so there i think the current system does allow to what allow for that to at least to some degree and combining your thought with grants also like providing a way to say okay i'm on this page i want to add some contextual help on this page within this page right you know and that seems very similar or complementary to what he's saying would you agree i think so yeah yeah okay so i think it's probably some combination of what already the functionality that already is provided by hook help with maybe something new in terms of like being able to add that help on the page which is hugely useful right so hi can can you say a little bit more about permissions and like how much thought you oh sure uh let's uh do you mean like which permissions are provided yeah yeah yeah um i can i can show you possibly i can type with everyone watching me here we go so we've got three permissions provided um administrator configured help topics so that's the ability to create edit and delete unlocked help topics um there's lock and unlock configured help topics and view configured help topics so in a lockdown system um where you just want your people who maybe have some content editing abilities they have access to the admin theme and um the admin pages and you also want them to be able to you know view help and you could say view you would if you turned on view help you would also want to turn on view help topics um view configured help topics and so that would be kind of an example configuration of a of a kind of limited access administrator who needs needed to have access and then for people who you trust and provide some training to um you would provide additional permissions probably with and the training would consist of consider you know which uh help topics are provided by contributed uh or core modules it would make it easier for us to update if you kept those locked and you know maybe provide um some direction as to which uh help topics are owned by the sites explicitly and should in can and should be edited um and maybe with some direction of like well you can add links to them in the related topics fields have there been any discussion around can you can uh oh thinking about for like content editors often you know there are certain help topics they don't need to know oh right and so that's where I would use the the related topics so like maybe you have um your top level topics or maybe per like area like department for example there is an issue for that okay great yeah so so you know there there would be there's a lot of flexibility currently on how you would design it um but I think it would be possible to like that domain would probably be like a top level topic with some related topics that are linked to from there um and with training right but maybe there but maybe providing permissions like you're saying like per section or per like if there was a category maybe like in a just like you could add taxonomy maybe to it and that taxonomy I'm just totally making up stuff off the top of my head at this point so it would some something better to be considered and discussed in an issue queue instead of just me spouting off random ideas oh okay so per topic even okay yeah so there's a there's a apparently there's an issue in in the help topics queue um and about providing per topic permissions so it'd be great to like be able to assign help topics to a role this is your domain you have free reign you know you don't have to worry about messing up the site and getting yelled at right that's a good thing so thank you Amber to you and Jennifer for working on this I can't wait to see it out I have a question so there's not a way with this system to have inline images is there I think there is actually okay um it's part of the whizzy way yeah that's not going to affect like the strings or anything it's it's going um yeah there is a image tag here yeah because screenshots so important yeah yeah um I don't know the technical detail of how I didn't do my homework on that but yes let's test it out let's like you know uh let's see how that works out it's definitely going to be a thing because screenshots are just an integral part of better help so so please uh you know download the patch and test it out and try an image and let's export it and see how it goes and people can not only um download the patch they could also download the sandbox project that's right yeah and install it as a module on the site which brings up the question um why try to convince the core maintainers to include this um from the sandbox into core why not promote the sandbox project to a full project let people install it as as a full-fledged Drupal module um get experience with it make improvements to it and then try to bring it into core so the answer to that question is um probably twofold so as a back uh one of the reasons why who who is uh who has who's familiar with um advanced help so even though there's a lot of familiarity with it like bottom line is it still doesn't have wide enough distribution and there's not a Drupal 8 oh and I just realized I'm over my time so let me just say the the the direct answer is because Jennifer doesn't want to she strongly believes that this needs to be in core she's been trying to get it into core since 8.0 um and joe it needs to be in core yeah I I will yeah so it basically what joe is saying is that it gets more visibility if it's in core more people will use it and it can get more traction so and you can document core so yeah yeah yeah thank you all I'm I'm I apologize for going over um thank you all for the great discussion um if you have more ideas I would love to talk to you in in the hallway um I'm I'm around for the rest of the week or um please go to the issue and um feel free to comment your support or your ideas and um and if you so if you give it a review please feel free to mark it as rtbc so that we can get on with our lives I mean so that we can get this into um as a an experimental module thank you very much no I think that would be that would be a yes right that's a good point too thank you thank you thanks grand I've been reading your blog occasionally my blog yeah at least I'm terrible at things but you blog occasionally I haven't blogged in so long so why do I'm so familiar with your name well uh we'll dribble as me and also like Portland group yeah yeah very sure just I I just post a lot on the the Portland groups yeah maybe that's what it is I think it's probably because of the my involvement with the Portland group I'm clearly anyway um we are yeah let me know okay and obviously I'm going to say that it's quite useful should I do it in the sky right you should be able to but the problem is that too many issues that get agg novice are then people anywhere in the world or against the threat so if we're going to the trouble of curating or I could also just go I'm taking it so I signed up to have a documentation and I don't have any specific things to work on currently I did that in part