 why advanced help  the advanced help system was designed to replace the original drupal help system which has several flaws that make it hard to create new help hard to maintain existing help and particularly hard to access help the primary goal then is to increase the accessibility of help meaning the ability of both the user and the help text author to access the needed tools to use create maintain and translate the help this system is completely separate from drupal s hookhelp in drupal 6 it actually coexists with it in the future it is hoped that it will completely replace it allowing hookhelp to be deprecated and removed messages added to the top of a page are not really help often these messages are an introduction to a form or a short blurb telling a user what to do with a particular page the problem is these messages are always there they are easily ignored and they come before the actual page in general when users are learning they want to see the page first then ask questions the reverse order is much less conducive to actually teaching a user how to use something by allowing help to be available on request the system conforms more naturally to how most people work advanced help is organized by topic with the hookhelp method help text is organized by url path this is fine if you have help text describing how to use a particular page or what a particular page does but ultimately is limiting because manuals and documentation are usually grouped by topic and those topics are determined by the material itself advanced help allows the documentation author to organize topics as he or she sees fit the only restriction really is that each individual chunk of text needs to stand on its own as a discrete topic what s more modules can insert their topics into another module s hierarchy this would allow the drupal core to create a task based help navigation system which allows modules insert topics into that navigation fluidly this allows modules to continue to keep their systems separate yet integrate into the main system advanced help topics are processed html in their own files this separation makes it easy to find and modify currently everything is lumped together in hookhelp in php strings that are run through t and there is a fair amount of php code necessary in this system that actually gets in the way of writing good explanatory text in fact requiring a documentation author to understand php at all is a detriment the idea that documentation writers need to have php development as a skill seriously reduces the number of available contributors html on the other hand is a much more common skill is relatively easy to learn and the amount of html needed to write documentation is only a little bit more than the html used in forum posts another benefit to not using php is that the files themselves are safe they are unlikely to include malicious php code that could take over the server or do worse things this means that these files can be used relatively easily on the drupalorg hardware so that a module s help files can be made immediately available without needing to download the module it also means that descriptions of the module can be made on drupalorg that are version aware can be corrected easily in cvs with patches but can also be made available with the module so that drupalorg is not required this also means that we could if we wanted package the drupalorg handbooks or a subset of them directly into a drupal distribution or a drupal addon so that drupal administrators can have drupal help without needing to visit drupalorg this can be valuable in locked down corporate environments and on planes but more importantly the handbooks can be made version aware much more easily than the current method on drupalorg the downside to this method is that these books can t easily be made dynamic though the use of alter hooks could allow a module to make modifications to the help as needed doing this could make the help files less useful when you take them out of context advanced help files are translated as a file it is actually not easy to translate documents as strings particularly when the language being used is very much unlike english in fact when translating a document the organization of the sentences may change drastically it is also a burden on the cpu to do this as you are indexing on very long strings translators have a much better time translating a document as a unit because of the presence of the entire context advanced help has its own navigation system by making use of a navigation system specified in a ini file which is not php code and therefore safe to use on drupalorg sites the help can be structured like a book which is typical of online manuals this is familiar to users can be organized and reorganized and allows a module to include significantly richer text without burdening the php code with having its help loaded unnecessarily this book can be navigated hierarchically as well making it easy to keep related topics together advanced help is indexed by the search engine an important goal of this system was to add searchability to the help by being able to enter keywords into the search box and find relevant topics we come up with a system that resembles the kind of help that comes with many operating systems this is very valuable when searching through manuals trying to find out how to do a particular thing this search is specific to the help meaning that the help will not be mixed in with the global node search this can be considered both an advantage and a disadvantage for the most part this help system is meant to provide help to site administrators and content searches should not find it the disadvantage of course is when you want to use it for end user help you will not be able to inline help can be brought in via popups in addition to the manuallike hierarchical navigation advanced help can also provide contextsensitive additional help through a popup while popups are controversial the argument for using them is that when getting help while on a form  a popup will not throw away a user s data browsers are not very friendly to input forms if they are not submitted and navigating away from the form can be dangerous there are various other solutions to this problem but each one has a drawback the drawbacks to popups are well known but mostly it is the irritation of having new windows when getting help though a popup is usually invited help should not interfere with what the operation the user is trying to complete it differs greatly from the uninvited popup which are usually ads or popups meant to prevent users from navigating away from a site these popups can be added to a page with text links or icon links  