Discussion: What would a better help system for D8 be?

subscribe

A few comments.
1) One of the places where d.o. documentation has faltered for me is being able to add screenshots. I would like the help system, no matter how it is implemented, to be able to allow for screenshots in tutorials. Currently I have non screenshot versions on d.o. and screenshot versions in advanced help.

2) As a module developer I would like to have official help. I would prefer the help that is inside my modules pages not include all pages that people have added under my d.o. user documentation.

3) If you have php in your help documentation how would that display on d.o.?

I want to work on improving things for 1) labels & description wich indeed are a bit different. Especially labels, those are essentially *are* the interface itself. Descriptions should be largely task driven copy, but definately room for helpfulness as well. We can improve a lot there by rewording labels for consistency and descriptions for task-focussed brevity. Out of scope for an issue about a docs-driven help apparatus, but the boundaries are blurry. (Also: think showing contextual error messages next to the actual field in your form. Is that help or?)

Lets not forget to keep a focus on how a new help system will *actually improve the overall admin/config experience* for builders/configurators (&devs &docs etc.

We should try and get a good phrasing of the question before giving answers :)
The 3 types of help you sketch are a helpful framework for thinking about that.
From labeling a single checkbox to pulling in content or links from d.o.
What kind of architecture does core have to provide here?

/end subscribe sketch ramble

subscribe

Subscribing. Would be great to kill filter tips as part of this effort (even if it's a followup patch to the main one):
http://api.drupal.org/api/search/7/filter_tips

We need to differ between

• Help pages containing longer texts, possibly sub-pages, etc.
• Short, contextual interface help (more than typical #descriptions, but much less than a full help page)

We need both. It sounds like this issue is trying to focus on help pages.

I fundamentally disagree with bullets 2-4 of the summary in #9. That's the design idea of the Advanced Help module, and while its general mindset is a step forward, it didn't gain the momentum and adoption throughout the Drupal community that it hoped to, and here's why:

2. Changes to help text should be discussed/proposed in a controlled manner (issues, patches or some equivalent, commits by project maintainers or some equivalent). The system for proposing, discussing, and making changes needs to be usable and understandable by non-specialists as in the previous item.

   A project should document its code, provide an intuitive user interface/experience, and expose contextual interface help. Issues are the wrong place to discuss help pages and documentation. Patches are the wrong tool for people who are able to document.

3. Help text should be version controlled within the project, and under control of the project maintainers for final approval and branching/tagging in parallel with the project source code. This doesn't necessarily mean that help text necessarily must be in files that are checked into the source code repository. If help text isn't in files checked into the repository, the system that is used needs to have the ability to mark a particular version of doc as relevant to a particular release, and for the project maintainers to declare "string freeze" and say that this branch can't change any more, etc., like we can with files that are checked into the repository.

   The idea that help/documentation must be directly tied to project releases is completely flawed. The situation is identical to translations. Most help/documentation is written after the fact, when people try to use, implement, or integrate something. Help/documentation has to be attached to major versions of a project.

   It's fundamentally wrong to freeze documentation. Help pages are living documents that constantly evolve over time, at any time, through contributions by everyone.

4. Help text should be translatable.

   ...and files are the wrong interface for help text in the first place. Help is content, and content is what needs to be translated. Translators need a proper and simple interface to diff against the original/source, be notified about updates, and any other feature that is only common for translation management. There's nothing to re-invent here, it already exists and will be enhanced over time.

We need to think modern, think Wikipedia. We need to remove barriers for writing, contributing, and translating help and documentation. Everyone needs to be able to contribute, regardless of skillset. Forget about everything that involves code, files, and patches - it's the completely wrong tool for the job.

Also note that translations of help/documentation are even more detached and disconnected from project releases.

how do we differentiate the "official" documentation

» Flag

Most project maintainers sadly don't give a shit about user documentation, so most "official" documentation is going to be "official", because the community agrees that it is correct.

Project maintainers don't have to be forced to be involved in this process. Why should I have to approve a typo or grammar fix? Why should I care at all? Why don't you (not you) just simply document the hell out of my project? Ask me to clarify details when needed, thanks.

distribute/embed in a Drupal site from the big wiki on d.o that is freely editable by anyone at any time

» This is commonly called Export and means a (un-editable) snapshot/copy of online documentation content that can be generated at any time on any given date for whoever needs it. Of course, tailored to your actual site. Download, extract, switch the documentation server URL to your own site, done.

We already have wiki-style documentation here on drupal.org

Right. However, this kind of help/documentation system requires a custom content structure, supporting cross-links and relations, heavily improved content editing features, as well as content translation management. Thus, think help.drupal.org.

Actually, I wanted to kick-start a first version of this system on a custom site/domain last year already, extracting and merging in the best ideas out of Advanced Help and DITA, and developing the remaining parts; but quickly figured that this requires D7, so deferred it until release.

I always envisioned there being 3 download links on a project page. Module, Documentation, Module with Documentation. For me I would like the documentation downloaded from there to be something I approve. I don't want it to be whatever is located in the online documentation that anyone can edit, because wrong information could be in there and I feel responsible for whatever comes downloaded with my module.

What I would like to see for help pages:
A website created where users could edit the documentation. ex. help.drupal.org
A specific module would be located at help.drupal.org/module_name
Translations would be help.drupal.org/module_name/fr/... Not sure if the existing translation would work or make sense since these would be huge chunks of text.
As a maintainer of my module I would be able to mark (flag, taxonomy) a page as official.
On a nightly build or when the maintainer asks for a build a tar file is created of all the official documentation. A user would extract that into mymodule/docs and then it would appear in the help system.

Obviously a lot more details are required to implement, but that's the general idea.

Just in case it wasn't clear I am happy for people to edit the docs. But I would like to be able to create snapshots of a documentation state and mark that official. Kind of like node/111111 revision 245 is the official one. Then it can still be worked on without having to potentially have incorrect information on the end users site.

As far as translations are concerned unless there are official snapshots I think translating documentation would be a nightmare. It would be like translating drupal core without a string freeze. Doesn't sound fun.

It would be like translating drupal core without a string freeze.

Not at all. We're not talking about t()/.po-file strings that entirely invalidate all of your existing translations when being changed. That's why we have and need a string freeze for t() strings. Not required at all for multilingual content within a system that provides common content translation tools.

@sun if you have a help page and you don't have a snapshot for translations if a page gets changed once a week wouldn't that page need to be translated every time it gets changed if you as a translater think each change is final? Wouldn't it be annoying to translators to do that?

It seems to me if I was a translator I would rather wait for the documentation to be determined to be completed by the maintainer before doing the translation.

No, content translation systems support a notion of marking translations as outdated, if required. The author who updates the source decides on that — if you fix a typo or some grammar or just formatting, no need to mark translations as outdated.

Additionally, translations don't necessarily have to be up to date at any point in time.

Overall, translatable content follows entirely different workflows and rules than t() strings. Drupal 7 set the foundation to properly handle translatable content in fields. Previously, we had the clusterfuck of creating separate entities per language, which required to build entirely separate trees of content, ensuring that cross-links between contents are actually valid, and all kind of related nightmares. With D7, the notion of translatable fields is in core, and the contrib Translation module exposes the corresponding UI for them. There's only one canonical content, which contains field values that can be translated — a fundamental requirement for large-scale documentation sites that are driven by volunteers.

I like the idea of keeping the longer documentation on Drupal.org (or help.drupal.org/docs.drupal.org - fully agreed there would need to be dedicated docs subsite to really make that work).

There was a real effort in Drupal 7 to improve the content and standardize the main hook_help() pages, but that was a last minute effort that had people not sleeping for days, and in the case of a lot of modules, needing to remove huge chunks of outdated text in favour of standardized linking to Drupal.org

I can't find the issue at the moment, but at one point people were discussing having a welcome to Drupal 7 video embedded in the default profile (i.e. hosted on Drupal.org, but viewable directly in new installs), that's something which this might enable as well.

It seems like people are talking about three things in terms of what happens though -

1. Moving the docs to help.drupal.org/project and linking to it.
2. Moving the docs to help.drupal.org/project and including some kind of help browser in core, dependent on the live content on Drupal.org.
3. Moving the docs to help.drupal.org/project and exporting that back to version controlled files that could be included with module downloads.

For #3 there is already http://drupal.org/project/helpinject written for that purpose, and it's not mutually exclusive with #1 and #2 (although all #2 and #3 are mutually exclusive in terms of what might be added to core).

@jhodgdon: The use-cases and workflows you stated are mostly common and the same for almost all multilingual sites. I'm not saying that the contrib Translation module provides all of these features yet, but well, that's basically the plan.

Subscribe.

And

> We already have wiki-style documentation here on drupal.org

No, we don't quite. I keep having to type things like HTML UL and LI tags, make links the hard way, and I can't rearrange the way content is structured. In a wiki, structure IS content. But all that's for another issue...

A lot of the things I'd like to see have already been mentioned and are in #27 & #29. I strongly agree with the principle of better and more seamless integration of online and in-site documentation.

I'd like to see a few things added/emphasized, though.

First, in addition to site builders having (optional) control over what docs get downloaded to the local site (#29), the docs team and/or module maintainers should have (optional) control over what docs could be downloaded. I think it is important to allow maintainers who wish to vet site included documentation to be able to do so, as redndahead mentioned.

Second, it struck me when sun commented "We need to think modern, think Wikipedia" that rather than thinking Wikipedia, we need to think Drupal. Specifically, we need to think Drupal as in Views and CCK/Fields/Taxonomy/etc. sort of way. While I think the documentation book hierarchies are very important and necessary, especially for people browsing and unsure what to look for, we also need need additional structured ways to help people find all the information they are looking for. (Search just isn't enough -- ever tried to search for help on, say, Views permissions? Or Features?) We need to take more advantage of the relational databasey power of Drupal.

As an example (near and dear to my heart :-), I've recently been dealing a lot with permissions settings. This is information that should appear within every (core/contrib) module's documentation, but it should also appear gathered together somewhere under the rubric "permissions". It should also appear under "set up", and under "installation". In addition, people looking at help docs about specific recipes or techniques should also get information about the relevant permission settings, and that information is also needed by people seeking documentation about permissions generally, set up, installation, etc., etc. And so on.

So, especially as it appears on help.drupal.org/docs.drupal.org, we need to make more use of the power of Drupal to present the same information in multiple places in an intelligently automated way.

Further, we need to provide obvious guidance/structure to help those contributing documentation to get it to appear everywhere it should (free tagging just won't do it!)

From the discussion so far, and my own thoughts, it seems to me that the sorts of information/tags/flagging/whatever we need for documentation chunks includes (but I'm sure isn't limited to):

• Essential/optional/etc
• Official (or not)
• Relevant common-to-most-modules topics (permissions, configuration, etc -- this needs more thought and may be multiple categories, and probably also needs to be expandable yet structured)
• Drupal core version
• Module(s) addressed/involved
• Module(s) version(s)

[Note that though I mention views/cck/taxonomy above, I'm talking general conceptual ideas here, not technical implementation suggestions.]

Third, there should be no in-site documentation that does not also appear on drupal.org. People should not have to install or even download a module (or core) to get access to all official documentation.

Fourth and finally (for now), documenters really, really need a WYSIWYG. Nobody should need to know any markup system, either HTML or wiki-style, to edit rich documentation text.

I came late, but if I understand correctly, this has the problem of being overly controlled. Drupal's current help system and the help presented by the advanced help module are hopelessly difficult to maintain because only a few people even know how they can be maintained. Even less people know where the information is. And then if you search for it online (like all the info that is in the views advanced help) you can't find it.

My overstated opinion is that all help wired into the code has been a feeble failure, and I'd rather not go that way.

I do want a controlled, focused handbook. But I think it should be online, have translation enabled (per this thread).

If what we are talking about here is to create a site that users could contribute to that would be downloadable into the project and incorperated into the distro with the packaging scripts, then I think that is a great idea. Ideally, the hooks for it would be provided as part of hook menu, so that you could get context and permissions along for the ride, although it would be nice to embed as part of form rendering as well. I don't really want to see yet another hook for the module maintainer to have to write. My bet is that it doesn't get written.

One of the big barriers to online docs is that you have to fit your docs menu structure into the handbook structure. Ideally module developers would be able to provide docs that are tied to their major releases in contrib. That way there can be views 2 and views 3 docs that you could switch between to see how things are done. The navigation context would only be relative to the project and allow you to switch between versions ghat match releases.

I don't think all the stuff about point 8 seems overly complicated. Product documentation should match release versions. Let release management practices copy docs, but all this tagging seems like it will just be a jumbled mess. Let the d.o resident code have quick nav to other versions tagged the same way api.drupal.org works.

Input fillters could help proovide the nav between local copies and d.o.

Just catching up here - I've been thinking a LOT about all of this in preparation for the core convo, and taking a step back from the specs, there are some questions/issues that keep coming back for me that I think we need to consider:

1. Consistency. More than anything, I think what will help the end users be better served by the help system content is for it to use a consistent method. The content in Advanced Help may be great, but it's useless if people don't know it's there. There should be a consistent place that everyone knows to look for all core and contrib modules' help content.

2. Core vs. Contrib. That said, I know that core and contrib have different needs/priorities. For core - part of the reason we keep so little content built-in is because of core string freeze (online docs can be updated anytime). This doesn't matter for contrib, because functionality can change wildly through minor versions and there is no reason not to keep updating the help text in code. But contrib has less consistent documentation and the community can't easily help improve that if the content is in code.

3. What is most efficient aside, how do we weigh the importance of consistency vs. having freely editable help/docs? Along the lines of rfay's comment #32 http://drupal.org/node/1031972#comment-4035164 I don't want to move to all of this being in code (even if it's easier for it to be consistent and controlled) because it will heavily restrict who is working on this, and that'd not good for collaboration (a good part of the day-to-day docs work is done by people who are not as technical, sure we can train everyone but it's still a barrier).

4. Essential or Official docs. I've been going back and forth on this, and there are obvious benefits to setting up a definition like this, *but* then who vets these and how? It could lead to a lot of unnecessary power struggles, and less collaborative work.

5. Help.d.o or Docs.d.o? If we have some kind of help server that allows us to update text through an online UI and push those into Drupal sites, how do we review/moderate changes? Do we pull straight from the online docs or have separate "help content"? Moving to docs.d.o is going to have fairly far-reaching implications for the rest of the documentation, so I'm inclined to use help.d.o but then we may end up duplicating efforts in the d.o/documentation.

6. If we have a help server, how do people get updated version of the content into their site? Is there a "update manager" notification?

7. Finally, I don't think that we want to make this implied to be the "responsibility" of docs team - contrib maintainers should maintain their docs, though anyone can help with that. But I think docs team needs to focus more heavily on keeping core (or any other deemed "essential" type docs) up to date as first priority, and then setting clear standards that contrib can use and providing support for contrib maintainers. (catch had interesting comments regarding this http://buytaert.net/drupal-7-development-process-retrospective#comment-3...)

The point of this initiative is to remove ourselves from string freeze and from having the docs in code at all.

This seems to be the critical point here, I'm just highlighting it as I suspect this is where consensus must be reached first.

I wrote about a new docs system on my blog at http://cweagans.net/blog/2011/1/31/building-better-documentation and at http://cweagans.net/blog/2011/2/2/building-better-documentation-part-2.

I'd like to see core docs included with Drupal, but I agree that they need to be removed from string freeze. I think that there should be some way to maintain the docs easily, such as a help.drupal.org site. But I also think that there should be some functionality in core that allows a Drupal installation to download an updated copy of the docs (perhaps to the files directory). I don't think this should use the Update Manager - I use help.module, but I will probably never use the update manager.

Another thing to consider is that there are a few types of documentation:

1) Developer docs
2) Site builder docs
3) User docs

I can see #1 and #2 being maintained by the documentation team. #3 is probably something that's specific to a given site. I know that I have built sites that are fairly complicated from a user standpoint - complicated to the point where using the site requires that the user reads the docs that were written for the site. That is, #3 would be docs generated by each site. I think we need to provide that capability for such a thing, but we don't actually need to write any docs that utilize the functionality.

i came here via #1056202: adopting localize.drupal.org infrastructure for drupal documentation

subscribe

subscribe

subscribing

+1

subscribe

I'm in

Here's an attempt for an architectural solution for help/documentation, as described throughout this issue.

Part 1a: The entity Documentation Page

This is the building block of help, both contextual help (type 2) and longer, detailed information and how-tos (type 3). It has the following properties/functionalities:

1. Main content, which may include HTML – just as with a standard node body field. (Wysiwyg or different kinds of markup are left out of this description, as this will depend on the site using the documentation pages.)
2. Project links, which will most likely not be able to be simple node references given the fact that we want to be able to clone documentation pages across websites.
3. Possibly the possibility to add screenshots and other images. And, I hope, other media.
4. The ability to manage some kind of official approval of documentation pages, and revisions of them.
5. Translation capabilities, where each translation will have the same revisioning process as the source text.
6. The ability to place markup in the text, to show/hide certain parts depending on which version of Drupal/module you want help/documentation for.
7. Some kind of path pattern, that tells Drupal/the help system where this documentation page should appear as a help link. I think this is a tricky part.
8. Probably a link to an external source, if the documentation page is imported. (There will at least need to be a universal identifier.)

Part 1b: Documentation collections

Documentation pagers are put into tree structures with the help of a "documentation collection" entity. Though it is probably theoretically possble to let the documentation pages manage their internal structure themselves, it would be an epic mess trying to make this work when the same page can appear in multiple collections – and pages should be importable to Drupal sites individually.

Part 2: Documentation updater

To import help/documentation pages to local sites, there will have to be something similar to the Localization Update module. It will allow you to do the following:

1. Select among the enabled modules and languages to choose which documentation you want to download.
2. Select how often you want to check for updated documentation.
3. On individual documentation pages, you should be able to set an option "do not overwrite if external source is updated" (or something like that). Maybe you should also have a global option blocking overwrites of all local documentation pages.
4. Set a path to the server to get documentation updates from.

Part 3: Embedding documentation links

I think a very good way of embedding documentation links is to use the Contextual links module, in D7 core. It allows adding contextual links to any part of renderable arrays in Drupal, meaning that you could add documentation to entire pages, selected form elements, blocks, field sets and what not. It fits well with our needs, and I don't think it is realistic to invent a new system that does what Contextual links does but in a better way. (If we find needs that Contextual links can't meet, it is probably better to extend Contextual links.)

The difficult part will be to have a parser that from information in each documentation page can find out where to add help links – which will be a #7 in part 1a above.

It is possible that we can learn something from how blocks can use path patterns for visibility settings, but I doubt that path patterns will bring more than a start to how help links should be managed. Currently I don't have any good idea for how to solve this.

Some additional comments

1. It has been discussed whether documentation pages should be nodes or some other kind of entity. I think this is a quite deep question, that potentially affects large parts of the Drupalverse. If we (and others) start inventing node-like entities, then modules like Content Access or other node-centric modules won't be useful to manage them. This will either lead to more generalized modules, in which case we arguably have created a parallel to node entities; or we will have entities that require new hand-coded solutions whenever we want to go beyond the very basic entity handling. Based on this, I clearly vote for having documentation pages (and collections) as ndoes.
2. I think that we will need to have media fields for images, movies or other attachments. I quick-and-easy solution would have been to embed image tags, just like the current documentation works, but if we use that approach then we would also depend on the text formats on the local sites. To depend on one or several media-providing modules isn't perfect, but I would argue that it is much better than requiring special text filter settings. Two options for storing media comes to mind: (a) help.drupal.org or (b) an external open and free media storage like archive.org. The former has the benefit of full control over the media, the latter the benefit of not having to take care of storage or bandwidth (though it would also require people to get accounts at, say, archive.org).
3. The translation of help pages cannot be managed in the framework as string translations at localize.drupal.org, since they are not (and should not be) translatable strings. They are content with translate capabilities enabled, where source and translation is much more loosely coupled. This doesn't prevent us from managing translations at l.d.o, but there are also benefits from having the translations at help.drupal.org (since people working with help page translations probably are interested in updating the source texts every once in a while).

the architectural proposal by itangalo seems very good to me.

#7 in part 1a of course will be of interest

Some kind of path pattern, that tells Drupal/the help system where this documentation page should appear as a help link. I think this is a tricky part.

subscribe

subscribe

-1-
Nice idea!
I did some searching and found the following three modules that kind of do the second part of what you describe – http://drupal.org/project/glossify, http://drupal.org/project/linkintel and http://drupal.org/project/keyword_link. None of them have any version for D7, unfortunately.

-2-
Also, big thanks for the writeup in #50.
I talked a bit with kvantomme at DrupalCon, and I think the right approach to DITA is to find a field structure for help pages that we agree on – after that it should be possible to add DITA as an alternative render mode for help nodes.

Finding a field structure for help pages might not be very easy, though. But if we get it right it would allow better structure and better searchability for help/docs.

Subscribing...

subscribe

Related background information exist in the long unresolved issue

"Help System - Master Patch" - http://drupal.org/node/299050

which was just updated to "won't fix" with a pointer to this issue here.

I would like to take part of GSoC this year, and I would like to improve the help system. Is there any specific task what I can take?

I'd gladly do the conditional filtering, if someone can support me as a mentor. What do you think?

Can we have a summary? I am lost where we define the problems, and where we talk about the solutions.

When I access help, I want the latest and greatest help.

Microsoft gets this: when I access help from Windows, Microsoft Office, or Visual Studio, I am taken to that latest and greatest documentation on Microsoft's web site. Any local help is only a backup in case the online help is inaccessible.

If I seek help from within my own copy of Drupal, I want to be taken to the latest documentation at Drupal.org. What I do not want is an archival copy of a portion of drupal.org that was snapshotted at the time of my Drupal version.

I feel that offline documentation for an online product is only addressing a niche need, such as browsing from an airplane or within datacenters with strong network isolation. Should covering those niches (offline documentation) be a contributed module? Wouldn't online documentation be far simpler to implement?

Drupal is about the online experience, the living web. Drupal should "eat its own dogfood": its primary help should be an online experience in the living web.

Not quite true. (I just tested to be sure). When I search for how to do a mail merge in Word, I get the documents for word 2003 not for Word 2008, so what we want is major version contextual links. I've suggested this before but it doesn't seem to be making it into the design specs.

It seems that people are currently focused on more of the edge cases for this design work. The core navigational linking, (what the structure is on help.drupal.org and how we make sure people can navigate between major versions of help etc.) doesn't appear to be getting much attention at this point in time.

@metzlerd: I just opened up help in Word 2010 and searched for mail merge. I was brought to the correct document at http://office.microsoft.com/client/helppreview14.aspx?AssetId=HA10199082.... Regardless, alleged flaws in another vendor's product doesn't make online help bad.

@jhodgdon: MSFT's on-disk help mainly works when the web is broken. I use Visual Studio 2010 and don't install the on-disk help. I'm almost always connected, so it doesn't make a big difference to me.

The argument for offline Drupal help is incredibly weaker than with VS 2010. Drupal is an online product. Unless you're a super haxxor, you're running your Drupal copy at a web host, so for most (vast majority) no web = no Drupal, either.

From my own perspective starting with a contrib module that implements a filter that presents the right contextual links for the version of drupal that you're using would be the best place to start. For the Unique id that's being talked about, I'd like to think that module/version namespaces would make the ideal way of connecting the link in code to help.drupal.org.

[help:views/6.x-2.x/development]
[help:views/6.x-2.x/create.filters] 

Where the stuff after help: is the tag that identifies which help document you're mapping to.
On the drupal.org namespace, another module would need to handle the dispatching of the data based on the module name and branch version identified.

There's some question about whether the version number could be automated from info file information for the module (from the system table) or whether this should just be at the developers discretion to change the strings. One seems more flexible, but the other moves well with the release management system.

A module at drupal.org would need to provide the correctly tagged document based on module, version and topic specified.

Does that sound like a start?

I wasn't advocating against online help, but rather pointing out that it's not just the "most current help", but rather the most current help for the "major version" of the software that you were working on. The 2003 product doesn't take you to the 2010 help. It's an important piece of the link between product release management that has been missing in this discussion. I don't think people are suggesting help that isn't online.

In my ideal world you'd be able to override the linked help documentation so that you could redirect certain "topics" locally instead of going to the help.drupal.org version. But even the "local" version is still an online document.

For example, if you have a different user registration process, you don't wan't the onlinle help for the user registration page to point to the drupal.org version.

The difference between our situation and the Visual Studio/Word examples you're using is that those products are closed products. You don't "change" the way they work like we do with drupal.

From a bird-level view, some of the recent follow-ups are correct - an online help system requires a standardized mapping between a local context and a remote resource.

AFAIK, no such attempt or solution exists for Drupal yet (although I'm also not too familiar with Advanced Help). But then again, it's also not hard to design: It's a reversed tree, and you start in a kinda abstract version tree. Naturally starting with a core compatibility, project short-name, and lastly its major version - followed by a help document path (still in a high-level topic tree, such as "admin", "config", "user", etc), and lastly, the help topic name.

We obviously need to discuss the level of detail that topics can be structured into (by default; i.e., the reliable minimum structure of help topics per project); e.g. all of the following would be possible:

http://help.drupal.org/7/drupal/configuration/system/site-information
http://help.drupal.org/6/drupal/configuration/system/site-information
http://help.drupal.org/7/views/2/configuration
http://help.drupal.org/7/views/3/structure/view/arguments
http://help.drupal.org/7/views/3/structure/view
http://help.drupal.org/7/views/3/structure
http://help.drupal.org/7/views/3/view/arguments
http://help.drupal.org/7/views/3/view
http://help.drupal.org/7/views/3/arguments
http://help.drupal.org/7/views/3
http://help.drupal.org/7/views
http://help.drupal.org/7

Although these suggested paths may look similar to D7's IA, they're absolutely not bound to the IA. What I'm technically after is that a module should be able to expose a help link on its settings page that points to

http://help.drupal.org/7/mymodule/1/foo/bar

regardless of whether that page exists. Kinda like adding [whatever] into a page on Wikipedia: the link works, but there may be no content yet, and you're invited to kick-start documentation here.

Additionally, we need to take into account that docs for one module might be identical across multiple core versions; i.e.:

http://help.drupal.org/5/wysiwyg/2/profiles/edit
http://help.drupal.org/6/wysiwyg/2/profiles/edit
http://help.drupal.org/7/wysiwyg/2/profiles/edit

...unless that module finally evolves and starts to differ in D7 or D8, so documentation authors/contributors likely want to "branch" off from the latest and greatest, having a new and different page for D7/8+.

In light of @metzlerd's comments, I'd strongly suggest to defer any discussion about input filters to a later point in time. The primary objective is to get a solid and reliable mapping of local contexts to remote documents done.

I just did a "sitdown" (the opposite of standup, where our team sits down and discusses a topic in-depth) last week on the help system and how to best host end-user docs, and they had some interesting ideas (and a couple showed interest on helping with the dev work on this).

We actually kept coming back to Advanced Help - I'd never really poked at it till last week, but maybe we should revisit trying to get it into core and then adding to that? Or am I crazy? *ducks*

We were also discussing a lot of the "how on earth do we handle screenshots" which I think is an important consideration, particularly if we delve into the idea of letting help.d.o host anyone's customized help docs too. Do we have defaults? Do we store the imagefield content locally while updating the text from the help server? Lots of questions still floating around.

Just throwing some ideas out there, interested in hearing what those who've been prototyping think about this stuff.

@metzlerd: "I don't think people are suggesting help that isn't online." I see what you mean. Whew!

But I am still concerned about talk of local archives. E..g, #46, the most recent architectural discussion, includes "To import help/documentation pages to local sites..."

Offline/archived help is increasingly a niche need, especially with online products like Drupal. In the spirit of 80% solutions, I say leave that <20% niche need to a contributed module, and let core help be almost 100% online documentation.

In other words, focus scarce development resources on a really good online help system and let others deal with the niche need.

@sun: Not sure that a reverse tree is needed? How about a unique tag per help page, then that tag is referenced when you request help from within the Drupal app? I think this is the "universal identifier" in #46? Somehow a unique identifier needs to be referenced from each help link within the Drupal product.

Subscribing

@jhodgdon:
I agree about not using advanced help.

I disagree that conditional text will effectively solve the problem for most major revision changes. It would be difficult to follow the existing recommendations on writing good docs. It would be better to provide easy ways to copy help text than to imagine, for example (configuring). I'm not suggesting that conditional text wouldn't be helpful, but I do think making it the major way you tie versions together is a mistake, and will lead to complicated hard to maintain documentation. Can you give me a counter-example where this concept has been put into place and works successfully?

It would be difficult (for example) for me to fathom the views documentation vs. views 2 documentation expressed simply as conditional text. The metaphors are just too different.

It would seem that "local" versions of help could easily be accomplished by overriding the help tag locally. You'd just then say, if I have this help tag defined locally then ling to it, otherwise link to help.drupal.org.

@sun:
I like the way you've abstracted the IA from the help links. Maybe it's just a decision to not use the major version in the tags, or move them to the end cause their optional:

http://help.drupal.org/7/views/structure/view/2
http://help.drupal.org/6/views/structure/view

In terms of writing the code, it would seem that you make it so a tag is a tag. But maybe you allow wildcard tag matching?
Help tag would be:

%/views/structure

Either way it seems that we have some disagreement among the community about which would be the best place to start. Maybe we should sort that out first?

@sun: Not sure that a reverse tree is needed? How about a unique tag per help page, then that tag is referenced when you request help from within the Drupal app? I think this is the "universal identifier" in #46? Somehow a unique identifier needs to be referenced from each help link within the Drupal product.

The fundamental idea to account for is that a topic can appear in multiple contexts, even within the same module. When speaking of contexts, I don't necessarily mean the current and very limited 1:1 binding of a system path to a help page as in good ol' Help module. It's clearly foreseeable that Drupal is moving away from that strict binding, and module functionality is getting exposed and intermixed in various locations. A way too simple example would be the "Manage fields" page, but that's still an own page, so try to forget about the page aphorism, but think of multiple contexts within a page context; i.e., modularity.

Your tag or topic might be "Arguments" or plain simply "Foo", but depending on the context, we want to show help for global/site-wide configuration options for Foo, or how Foo can be used by admins and what all the options in the UI are meaning. There might even be an end-user-facing part of Foo. Hence, there's a substantial help topic difference depending on the context, and that needs to be identified in the topic's path. When designing this carefully and cleanly, there won't be much (or even any) manual work required to organize/put help topic pages into a browsable/explorable "book" tree/TOC.

b) [...] we want to avoid having totally separate pages for each version of everything. We'd rather use conditional text where possible. But something like this probably makes sense.

It looks like we have to backup these statements with actual research/analysis data. AFAICS, almost all help pages for Drupal core have large differences between major versions. The same also applies to different major versions of modules, because, well, if there were no major changes, then there also wouldn't be a new major version. (I don't mean core compatibility here)

It might be possible that conditional text may be helpful in some cases, but when looking at the major versions of my modules, I guess at least 50% of them would need entirely different pages per major version.

b) [...] I'm also pretty sure we don't want a completely open wiki on help.drupal.org for the "official" help, but that hasn't entirely been decided yet, and probably people would at least have the option of contributing a suggested page.

I do get behind the idea that an "official" (closed, or, not freely editable) help would work for the main help topic pages of Drupal core. However, considering 4,000+ contributed modules, I don't think that the same "official help page" pattern is remotely able to work out.

Frankly, I don't see any reason why the help/documentation for modules shouldn't be completely open for everyone. In some of my contributed modules, I'm actually relying on the community to write proper documentation pages. Not because I couldn't write them myself, but because my time is better spent with fixing actual bugs or adding new features. Almost everyone can write docs, and I'm always able to fix, tweak, or clarify them afterwards.

Developers should be able to quickly and simply specify "Hm, this piece of functionality could use some UI docs, so let's associate a topic... tick-e-tick... '#help' => array('module' => 'mymodule', 'audience' => 'admin', 'topic' => 'config/functionality'). Profit.

Regarding on-line vs. inline [help.drupal.org vs. in your own site, many comments between #65 and #73] - If you pull the help into the site, you have better options in regards to what to display to whom, whether to completely hide conditional text that doesn't apply, decisions about what help you even want and what you don't want available (e.g. maybe just beginning level help?), and can add your own site-specific help. I agree that having the option to not pull it in and use help.drupal.org might be good for some sites, but I think most sites have some site-specific help available, so there should be an option for a site builder to create their own outlines.

It's not clear to me how this adds value over a really good online help system. I mean, so what if a user finds out about more features than he has access to? I'm an IT professional, and this happens all the time. I love well-informed users.

I'm a little concerned about the idea of conditional text. At the top of this isue, versioning the help text in git was rejected because it makes documentation maintenance complex. Won't conditional text add a lot of complexity while providing little benefit over well-written documentation?

re #75 - just to clarify, i didn't mean to use advanced help as-is. ;) i meant more like improving upon it, since it does have some useful pieces, such as allowing more than one page of help per module, and more easily editable text (as it's just straight html).

@arianek: That's still HTML in code vs. HTML in a node (or any D7 entity) though. There are many people who're able to document, but don't necessarily know HTML, how to patch, or how to get behind any other needless barrier being involved. In terms of this effort, the only interesting piece of Advanced Help is its internal mapping of help topics/tags, which also happens to lead to a browsable, hierarchical (tree) documentation structure. However, in AH, it's guaranteed to be limited to a certain major version of a certain module for a certain core compatibility/version. And while data can be manually copied/synced between branches, it's in fact a duplication of data. The biggest pain point however is that user documentation that lives in code is always outdated, no matter how hard you try (which is the exact same reason for why we detached translations from code repositories).

@sun - absolutely - it's a step up from needing to write PHP though, since many docs team members can write HTML quite competently. patching is another story, of course. so for sure an editing UI that removes that step is quite ideal - was just wondering if there any useful bits we could build upon from AH (as we've abandoned it as part of the discussion, and many contrib modules do use it presently). just to be sure i understand the last 2 sentences, you mean that it wouldn't be easy to update the help pages along with any minor version updates?

it seems that the idea of openly editable help server pages isn't something that people are too keen on, but that it's near impossible to keep the content up to date otherwise. ideas on a workable compromise, anyone?

I'm open to having a section where anyone can edit the pages, but no one can create new ones. No one has really ever updated my documentation, so I'm not worried about it being editable, but I wouldn't want any new documentation to appear until I approved it.

An idea would be: There would be an "official" documentation section. This section would allow anybody to edit the documentation, but it wouldn't allow them to create new pages or delete the pages. Then there would be an "Unofficial" documentation section. This would allow anybody to create and modify any documentation.

permissions for creating new vs. editing existing documentation being up to the module maintainer.

In my mind, the code defines, creates, and limits the possible help topics. Help/documentation topics that are not linked to actual code are never exposed, so there's no point in creating such pages in the first place.

Perhaps that's also some source of confusion regarding my "wiki" suggestion, sorry. I actually mean a kinda special type of wiki -- developers decide through their code which pages/topics/tags can exist and linked to, and users/contributors can fill in those topics with actual content.

We were just discussing this question internally at Palantir the other day, and from the page jhodgdon linked above it looks like we're thinking along similar lines with a new dedicated Help entity.

One item I would note is that if we have a custom entity type then we can do all sorts of magic in terms of how and where data gets stored. To wit, if help entities use UUIDs then we could have the entity controller first check for a help page locally in a DB (for local help text), then locally on disk (for module-provided help, or more likely help text that we provided to the client that we don't want them editing), then on a remote server that Palantir maintains (via REST), then on d.o (via REST).

That list of fallbacks can be configurable, so a given site can have whatever remotes make sense for it, including d.o or not. Add caching so you don't have as much remote traffic and you have multiple remote authoritative sources for content, a potentially local definition of IA (or possibly mixed if we do it right), and because the Drupal site itself is making the request it can specify what Drupal version (or module version) it wants, in case it matters to the remote.

And because that's configurable per site, it means we can customize the help available on a particular site as needed for each client, or for each Drupal distribution, or for each individual site, to the extent that we need to and it makes sense.

I just thought I'd throw that out as a potential solution to the offline/online question. We can in fact make that a site-specific decision.

I'm not sure how we would identify "newbies" on my own sites, so I don't quite get that. How would such a determination be made?

But it seems that the permissions structure would naturally be taken care of locally. That is you don't display the help link to people who don't have the right roles, so you don't need to pass that off to drupal.org, do you? I don't see any value in hiding documentation on drupal.org form anyone based on any reason.

Some fundamental questions to answer:

1. Is the online help entity just a specially tagged node on help.drupal.org (i.e. a node with an alternate access path: the help tag)? This is what I was thinking, but it seems there are some other assumptions being made out there. IF not a node is it stored in DB or on the file system?

2. What is the format of the UUID that gets used in code to reference the help entity?

3. Based on the answer to 1 Is the "help import" functionality basically implemented as a node import or are we talking about an alternate d.o. entity?

It seems like we'd all get on the same page much faster if we answered these core questions, and I don't see a path to an implementation plan until we get them answered.

When I red the spec (and I have several times now) I found that question a bit open. Know that I am reading and rereading the spec for changes all the time.

What's the rationale for this decision? It seems like it would be a lot easier to implement if it were just a node?

[We don't want to use Node, because it serves a different purpose, might have different permissions, shouldn't be part of site-wide RSS feeds, etc.]

That could be said of some nodes on most sites that I set up. There are mechanisms out there to control this. In fact I often set up localized help on my site that are in pages. Throwing away nodes throws away a ton of flexibility and features, and we will basically be reinventing a CMS to hold the help pages. Are we sure this is the right decision here? If it were being stored as part of the file system I get it, but once it's in the DB, why not a node?

Sorry I missed that up to now.

Because a node is "user content". Help text is "system content". They're fundamentally different concepts, and should have a totally different editing workflow and life cycle. Plus, per #90 we may want help pages to be transparently-remote, or live on disk instead of in the DB, etc.

Nodes still have a ton of baggage that we don't want, like having to deal with the node access system. (Although hook_node_access() does help there somewhat.) The parts of nodes we do want, I would think, are CRUD and Fields, which is what an entity provides. (Well, the R anyway... Hopefully that gets fixed.)

Ok I'll fade away into the sunset here, although I'm still a bit dubious. _Online_ help is not fundamentally a system concept, especially when people keep likening it to a wiki. I'd argue that drupal could make a killer online help editing system for other applications as well (dare I say including MSOffice). Imagine howto's with videos etc. I guess others are envisioning separate sites for help vs. documentation (which I think of in the same breath). Get ready to reinvent: taxonomy for categorizing help, node-access for implementing the permissions model, page caching for performance on help.drupal.org, book like menu structures for managing the outlines, notifications or subscriptions for notifiying editors of changes to the docs and probably more that I can't think of. We are talking about managing content on a help.drupal.org web site aren't we? Aside from labeling at "system", I've yet to hear anything that is fundamentally different about "system content" vs. "user content" save who can access it.

If we're going down the road of #90, then I'd advocate staying out of the db, except for caching and indexing structures. That way you have something that can be included in version control etc. still, which is one of the advantages of that approach. I do a similar thing in project forena where I store report data as files on the filesystem but provide a drupal forms based ui for editing them and it works well.

If you want to maintain the ability of "file-system" based UUIDs, then I'd suggest revising suns concept of UUID's to be more namespace ('e.g. d6.views.2.views.arguments) So that files could be stored easily on the file system without necessarily creating deep directory structures (alhtough some may find that cool).

Wow. It is not often I return to drupal.org discussions I am involved in and find 20+ new comments. Cool!

I'd like to argue for a help solution like this:

* A help entity that stores (conditional) text, screenshots, video or what have you. No surprises there.
* It also stores a UUID (which I for now would argue is the URL of its origin, for easier copying between sites).

We also need something that tells Drupal where help links should appear. I argue for using the Contextual Links module for this, since it can insert nice links more or less anywhere(?) in the $page array. The tricky part is probably to define help inserts in a way that allow wildcards in the right way -- but that's a technical issue I trust that can be solved.

I would argue for not storing these links as part of a module and not a part of the help entities, but as part of a help collection entity. Why?

1) Having the link definitions as part of the help entities would require having the help entity locally in order to link to it.
2) Having the link definitions as part of a module makes it much more difficult to extend them by configuration.
3) Having the link definitions as part of a separate entity makes it possible to in one go have (a) a simple importable entity that gives you, say, 'help for editors', and (b) a structure of the help entities -- possibly hierarchical.

As has been suggested already, the help links point to (say) http://help.drupal.org/7/drupal/configuration/system/site-information. It doesn't really matter, but I would argue for putting all version numbering at the end of the URL, to allow the local link builder to add any version number of the relevant module, and also easier fallback where the URL is interpreted. I could even argue for using a link of the form http://help.drupal.org/drupal/configuration/system/site-information#7 instead, but it really doesn't matter as long as there is reasonable fallback both when the link is built and interpreted.

As also has been suggested, there should be a configurable chain of places to look for help pages, from local entities to remote stuff from drupal.org. (I also argue that there should be import capabilities built into this, to allow editing a local copy of remote stuff.)

Phew! What would we get from this

• You could pre-package your module with a help collection entity that points to the five help pages you like at help.drupal.org -- inserting links at the right places on your site.
• The help collection could be viewed in itself, displaying the five help pages in a tree structure.
• Someone else could build a help collection of seventeen help pages, twelve of which are at help.drupal.org and the rest at other places that support the required functionality. Anyone could import this help collection, and use it on their sites.
• If two help pages need changes to match your specific site, you can have these downloaded to your site and edit them locally. Local copies would be prefered over remote ones, so the help collections wouldn't need to change just because you have some help pages locally.

Awesome!!!!!! Quite like the direction this is going. And @crell we have been talking about how great this would be at work too, so when it comes time for development I can see if we can get one of our devs to help out as well. :)

I quite like itangalo's idea above about the URLs eg. http://help.drupal.org/drupal/configuration/system/site-information#7 that would be quite useful in the case of any missing docs, having a fallback to the main URL.

@98 This sounds great. Let's make sure we don't require any urls on the help site be based on urls on the user site. I.e. configuration/system on help site having to match to configuration/system on the users site. At least for a views related module this wouldn't really work. Not sure if that's what was intended with the url examples, but just wanted to make sure. I prefer the anchor version of the url for the reasons that arianek described.

@100: As I see it the help path (eg http://help.drupal.org/drupal/configuration/system/site-information#7) is completely independent on where the help link appears on your site. (You might of course have a module defining help paths dynamically based on the currently viewed page, but that's a whole different matter.)

In my head I have a structure similar to this:

<help collection>
  <help page reference>
    <original help path>http://help.drupal.org/drupal/configuration/system/site-information#7</original help path>
    <actual help path>help/92</actual help path>
    <help display places>
      <contextual link pattern>admin/config</contextual link pattern>
      <contextual link pattern>admin/config/system/site-information</contextual link pattern>
      <contextual link pattern>admin/config/system#page-content-system_main-main</contextual link pattern>
    </help display places>
    <help page weight>5</help page weight>
    <parent help page>http://help.drupal.org/drupal/configuration/system</parent help page>
  </help page reference>

  <help page reference>
    <original help path>http://help.drupal.org/drupal/configuration/system</original help path>
    <actual help path>http://palantir.net/help/12</actual help path>
    …
  </help page reference>
</help collection>

(Please convert the structure to any coding standard you prefer. Serialized JSON is fine.)

I took a closer look at how to make help link appear where you want to, and went back to the module Advanced Help Injection and Export. It allows injecting help links to arbitrary form elements, and also to pages as a whole according to some customizable patterns. (The attached image shows possible mappings when adding a help page on the path admin/build/modules.)

It could be a good idea to mimick this approach, and combine it with "paths" for the $page array structure. For example, the contextual link pattern admin/config/system/site-information would have a help link displayed for that page as a whole, while node/%/edit#content-system_main-body would have a help link appear at the body elements on all node edit pages. Hopefully it can be generalized to include wildcards in the second (render array) part of the link pattern, for example to insert a help link to all "add another item" buttons (regardless of where in the $page array they appear).

I hope what I'm writing makes sense. If it doesn't, I'd be happy to either (a) try to explain more or (b) listen to why this approach won't work. :-)

Forgot the screenshot from Advanced Help Injection and Export. Sorry. Here goes:

To maybe defer the above discussion about contextual text vs. separate pages for major versions we could maybe standardize on target URLs of the form:
http://help.drupal.org/drupal/configuration/system/site-information?vers...
(instead of http://help.drupal.org/drupal/configuration/system/site-information#7)

That way it would be up to the help provider if he renders a separate entity or if he renders the same entity but with conditionally different field values (or whatever). On help.drupal.org we could then (possibly) utilize both methods, depending on the use-case.

A user (content editor for example) probably does not know off-hand which version of Drupal and various modules he/she is using on a site. So if we went to a purely on-line help model, we would need a way to pass that information to help.drupal.org when requesting help, as well as other factors like "this person is a beginner" and "this person doesn't have this permission". If a site builder sets up custom help outlines on their site, they can choose display options on a role basis (at least according to our specs).

But if there was a UUID associated with drupal.org help pages, then the module maintainer could correlate each help link within each version of the module to the corresponding UUID.

> I mean, so what if a user finds out about more features than he has access to? I'm an IT professional, and this happens all the time. I love well-informed users.

In my experience, the opposite is true. Users will be confused if they read about things they can't do -- heck *I* would be. If d.org told me I could wibble the foobar and I couldn't see the menu link or the form element, I'd be filing an issue / bugging people on IRC. Site admins don't want that.

I think being able to tailor the help to your own site would be a brilliant feature, and take our online help from being a necessary but often ignored addendum to being a crucial part of the Drupal install.

> Get ready to reinvent: taxonomy for categorizing help, node-access for implementing the permissions model, page caching for performance on help.drupal.org, book like menu structures for managing the outlines, notifications or subscriptions for notifiying editors of changes to the docs

All those need to be reinvented for entities anyway -- we'd just be jumping on board that process. And it's not that much of a reinvention process anyway, just generalizing what nodes do.

In general, I'd also like to give a big +1 to the points jhodgdon and sun and others are making.

The help system should apply to more then just administration. I've made complicated workflows where I used hook_help to guide the user. We should not restrict where this applies.

the site admin can create help topics that are not necessarily connected to a particular admin screen or page on the site. For example, they might want a "Creating a new section" topic that covers adding a menu, a block, some content, a context, etc., and isn't tied to a particular admin screen. So I don't think we want to just say "all help is tied to the code", and certainly if we have help outline navigation and searching, all help will be reachable.

However, fundamentally, we have to differentiate between help/documentation that is linked (or mapped) to code, and arbitrary additional pages, which are not.

I totally agree that an online help/support system has a huge potential for extending our help/documentation with closely related additional things - HowTos, Tutorials, FAQs, etc. But these things are solely built online around existing help topics. They are not tied to any code, and as such, they don't have the same fundamental requirement of being referenced from within module code, which is one of the primary challenges we need to solve.

We need to ensure to clearly differ between "online pages referenced from code" (topics) and "extended online pages that are surrounding/extending topics or entire manual sections".

if help entities use UUIDs then we could have the entity controller first check for a help page locally in a DB (for local help text), then locally on disk (for module-provided help, or more likely help text that we provided to the client that we don't want them editing), then on a remote server that Palantir maintains (via REST), then on d.o (via REST).

Definitely. But for the sake of making progress, we should defer the problem space of being able to "export" and potentially override the topics (or entire sections) of the online manual to a later point in time. It's a different and secondary aspect of the system. The actual online manual system may very well be a completely different implementation than the locally exported, overridable, but also synchronizing local help system. So there's also not really a need to say yay or nay for using nodes or entities right now.

The primary discussion we need to have right now is to figure out,

1. How local code is able to reference/link to online topics.
2. How online topics are structured, entered, created, and updated.
3. How online topics are quality controlled and maintained.
4. How access to online topics can be controlled or limited (or not).
5. Where and how links to online topics should or can actually appear in your local site.

The ideas and considerations on these questions are still extremely fuzzy, so it doesn't really make sense to start discussing technical implementation details.

@Itangalo:

http://help.drupal.org/drupal/configuration/system/site-information#7

Note that PHP cannot read the fragment part (#) of a URL. Only JavaScript is able to do that.

On your help collection/page reference proposal: Looks a bit bloated to me. All we need is a standardized (and locked down) topic reference resource format, a manually defined UUID following a predefined syntax, as discussed earlier; e.g., might be represented as a path, 7/views/3/structure/view/arguments, as a namespace-alike tag, d6.views.2.view.arguments, or might even use the HTTP request Location or request Body to pass keyed parameters,

core=7&module=views&major=3&task=structure&context=view&topic=arguments

However, again, that's way too technical for now. To find the best technical implementation, we need to know the requirements, which we don't know yet. We need to discuss the level of granularity of help topics/tags that are referenced in code. Whether these references should or have to supply any kind of context information or not, aso.

Still sounding good - though tbh, I'm getting a little lost in the technical stuff here. I wanted to check in on whether this is still going to support some fashion of custom help that site builders can add to further support the site admins? That was discussed more early on when we were exploring this whole idea, and it's not clear to me if that's not really in-scope anymore.

(ps. hope it's ok i abused my admin perms and fixed @itangalo's screenshot that wasn't displaying properly) ;)

I am very concerned regarding the user interface considerations required for the site-builder as outlined in the wiki. Some of the features discussed here seem to be aimed at a very specific audience, those who supply in-line help for there clients. I spoke about this briefly with jhodgdon, but I want to stress it once more. Because the interaction patterns required to make that kind of work, are quite special and I am not sure why that couldn't be dealt with in contrib.

In my experience, the opposite is true. Users will be confused if they read about things they can't do -- heck *I* would be. If d.org told me I could wibble the foobar and I couldn't see the menu link or the form element, I'd be filing an issue / bugging people on IRC. Site admins don't want that.

If a user is sophisticated enough to file support tickets at drupal.org, the user is sophisticated enough to use Google or the drupal.org search engine to find any content, all of which will be available online regardless of any restrictions suggested by any instance of Drupal.

That's why I think the idea of limiting what users see at drupal.org is silly. Shouldn't even be designed into the help system because it's unworkable from the start. The focus has to be on really good, up to date, rich documentation, not on limiting access to free data.

I don't think it's about limiting visibility of documentation, just curating it.

However, fundamentally, we have to differentiate between help/documentation that is linked (or mapped) to code, and arbitrary additional pages, which are not.

Depends on who "we" is. If "we"=each module maintainer, then it's super easy--in the module, where the module maintainer specifies help references, he just references the UUID of the Drupal.org help page. Ancillary pages just complement the "blessed" help page.

If "we"=drupal.org or the wider community, seems like we have a hot mess.

But for the sake of making progress, we should defer the problem space of being able to "export" and potentially override the topics (or entire sections) of the online manual to a later point in time. It's a different and secondary aspect of the system.

Yes, it's a niche need and somewhat of a pre-web 2.0 viewpoint, undeserving of core inclusion. Should be relegated to contributed module(s).

The primary discussion we need to have right now is to figure out, ... The ideas and considerations on these questions are still extremely fuzzy, so it doesn't really make sense to start discussing technical implementation details.

Not sure it's that hard. Seems like a simple topical hierarchy should work? Given Drupal community enthusiasm, can we set up a good wiki-like area and let this form by accretion? And wouldn't module documentation simply start at some root point for each module? That is, a module would have a "root" page, and the module maintainer could bless certain pages within the module documentation by referencing their UUIDs from within the module's help references?

I'm a bit confused at the comment regarding exporting help pages. I don't think I was talking about that. I was more talking about using UUIDs (not URIs) as a loading mechanism so that we could allow an index to be built that only mentions IDs, not locations, and then the entity controller could find them from wherever. That is, help pages specifically do not need to be exported to a local site but could live on any number of remote systems.

I suppose a side effect of that approach is that one could "override" a remote help entity by using the same UUID in multiple places, but that's more of a side effect than an intended effect and I'm not even sure it's one we should encourage. :-)

> If a user is sophisticated enough to file support tickets at drupal.org, the user is sophisticated enough to use Google or the drupal.org search engine to find any content, all of which will be available online regardless of any restrictions suggested by any instance of Drupal.

I was talking about me as an example.

I regularly see users who will just Mash The Keys Repeatedly if confused.

I spent some hours today examining how help links can be inserted into Drupal pages. My approach was to allow a general render element into an arbitrary part of the $page render array. The result is in a sandbox project called Inject render element: http://drupal.org/sandbox/itangalo/1120836.

From the project description:

The core part of the module works with two parameters:

1. A renderable element, such as a contextual link to a help page
2. A string description of where this element should appear in the $page array, such as content-sidebar_first-system_navigation.

To make this really useful it must also be possible to use wildcards in the string description, such as content-%%-field_text-und-add_more. If you would like to do this, or have ideas on how it could be done, feel free to join.

I think it's a good idea to branch this off into a separate issue -- and maybe we should do that with more topics in this thread -- but first I'd like to know if people find this a sensible approach for inserting help links. What say you?

Edit: This feature relates to requirement 1 listed on the wiki page, header General Considerations and Requirements, and also the section Contextual linking on the same wiki page (as well as some comments further up in this issue).

I suppose a side effect of that approach is that one could "override" a remote help entity by using the same UUID in multiple places, but that's more of a side effect than an intended effect and I'm not even sure it's one we should encourage. :-)

Then, by definition, you don't have a UUID.

And wouldn't module documentation simply start at some root point for each module? That is, a module would have a "root" page, and the module maintainer could bless certain pages within the module documentation by referencing their UUIDs from within the module's help references?

That presumes that online manual pages needs to exist before code is able to reference it.

From a developer's perspective setting up and writing user manuals is a second, delayed step. In an ideal world, I'd be able to reference an online manual topic from my module's code, regardless of whether it already exists or not, because all I know at the point of writing the code is that "this piece could use more elaborate documentation for users".

That presumes that online manual pages needs to exist before code is able to reference it. ... From a developer's perspective setting up and writing user manuals is a second, delayed step.

What I'd like to see:

1. At time module owner realizes a help page is needed, he creates a blank new page in the help system. That's when he gets UUID to add to the help references in his code.
2. Module owner briefly writes intended purpose of page. ("This page will document feature Y of module X.")
3. By the time module is released, module owner either creates documentation himself or "releases" page to crowdsourced content creation.

With that, it is reasonable to require pages to exist before code is able to reference it. Otherwise, the process of reserving a UUID in advance seems cumbersome.

Other alternatives include:

• A way for module owners to hide documentation pages. If the UUID is referenced from the module, the user visiting the UUID will get a friendly notice that the page isn't yet ready. That page may suggest more generic documentation.
• Module owners might stub out help references in their code but wait until the last minute to create stub or completed documentation pages, and at that time reference the UUIDs.

Simple is usually better.

subscribe...

subscribe

Tagging.

latest progress can be checked here: http://groups.drupal.org/node/174499

Please feel free to share your suggestions on help system improvements here: http://drupal.org/node/1283496

Subscribing and interested in contributing.