Posted by LeeHunter on May 4, 2010 at 4:37pm
4 followers
Jump to:
| Project: | Drupal core |
| Version: | 8.x-dev |
| Component: | help.module |
| Category: | feature request |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | closed (duplicate) |
Issue Summary
The current approach to user help is a significant barrier to following universal best practices for technical communication. The result is poor quality content in the help system and a significant duplication (i.e. waste) of effort by people working on Drupal documentation. If the shortcomings can't be fixed, we'd be much better off just getting rid of the help system completely and concentrating on the D.O.-hosted documentation.
These are the critical high level requirements (in order of importance):
- Single-sourcing: Anything that is documented should only be documented once. Any changes or improvements made to this single source can then be published to multiple channels (online help, website, PDF, whatever). This is not possible in the current system since there is a total disconnection between the content in the help system and the content on drupal.org.
- Task-oriented content: Good documentation recognizes that users almost always come to the documentation seeking a procedure for performing a specific task. Therefore content is structured around what the user wants to do. A poor alternative, but relatively common, approach is to structure the content around describing the UI. A very distant third possibility is to structure around the application itself and unfortunately, that's exactly what we see when we look at the help page (/admin/help) in Drupal: a list of modules in alphabetical order with nothing to guide the user to the actual tasks that they might want to perform.
- Modular, topic-based content: On Drupal.org, the docs team is moving towards something close to the DITA standard which involves breaking down content into standard information types. One of the benefits of DITA is that a given topic can be reused in multiple "maps" or document structures (i.e. single sourcing). This approach doesn't seem to be supported in the current help system.
Comments
#1
+1
#2
subscribing, but i'm unclear on what exactly you feel is so broken or unhelpful - just the way help content is created? or the content itself? jhodgdon, myself, and several others put countless hours into creating a docs standard for the help pages, and rewrote and updated them ALL for D7 core over the winter. it would have been nice to have this come up before then. :-/
#3
1. Should be a different task in the Documentation webmasters queue.
2. + 3. sound nice, but it would be a much better discussion if you could make clear what exactly you mean, by writing a help text for an example module or providing a mock-up or something. Also see #299050: Help System - Master Patch which contains tons of information on the (failed) effort to revamp the help system in Drupal 7.
#4
tstoeckler - there was a major overhaul of the help pages for D7 over the winter (see http://drupal.org/node/537828) but it was focused mainly on having a consistent structure and improving the content (which is still targeted towards a site admin or developer, and not the site's end user).
#5
Right, I was aware. And if I understood LeeHunter correctly it already goes a long way in terms of 'Task-oriented content'. The issue I linked to, was about overcoming other shortages in our current help system, namely being able to provide help pages as html files. This should be a starting point for discussing a help system revamp, as an immense amount of thought and discussion has gone into that issue, concerning workflow, translatability, usability, etc.
#6
re #2 Sorry I wasn't around much on D.O this winter and wasn't really tuned in to the discussion/work that happened re. the help system. I'm not sure though that it would have made much difference as the D7 help system wasn't being worked on.
As I pointed out in my original post, we're creating two parallel sets of content on the same topics and this is never a good thing. It's really really important that we single source content. Believe me, this is a totally fundamental concept for technical communication that should be the highest priority for the Drupal documentation. We just can't continue along the path of writing stuff on topic X for the Help and then turning around and writing a different take on the very same topic for the Web. There's no valid reason for doing this, other than the lack of a system for single sourcing.
The second problem is that we're organizing the content around the modules (aka chunks of software). This is reasonable for developer-facing content but it just doesn't work for user-facing content. I realize that this is a challenge with a product which is highly modular, but I don't think it's an unsolvable problem. I get the sense that developers don't really have a feel for this issue because they're used to viewing Drupal in terms of a collection of modules. Unfortunately, that doesn't provide a coherent view to the user who sees Drupal in terms of a role that they have to perform on the site and a variety of tasks, which generally don't map to the module view. I wanted to note that anyone who uses the web interface in any way - whether to install, build and configure a site or to do administration work - is really, for the purposes of the online help, a "user" and should be able to view Help organized by role/task.
One further note: we also should probably have some GUID-type system for tying each screen (or maybe even specific regions of a screen) to the documentation on Drupal.org. That would facilitate both single sourcing and context-sensitive help.
#7
closing as duplicate to #1031972: Discussion: What would a better help system for D8 be?