Drupal 7 will (hopefully) see the introduction of a new and completely overhauled help system (read: starting from scratch).
However, this mean that all documentation must be re-written.
This is not a job for one person! We need everyone to pitch in and help (no pun intended). If everyone can write two (2) pages, then we'll be very well off.
The kind people at the Help System group on groups.drupal.org have assembled a workflow for you to take part in. Here's how to write a help page for a module:
- Log in here. If you don't already have an account, you can log in with
YOUR_DRUPAL.ORG_USERNAME@drupal.orgas your usename and your drupal.org password as your password - Navigate your browser here to start your new wiki page.
- Choose "Drupal Documentation Task" for the "Group categories" vocabulary; and
- Choose the name of the module for which you are writing documentation for the "Help topic module" vocabulary.
- Fill in the title and the body to those that you wish to appear on your help page
- Be sure to adhere to the guidelines
If everyone can do two (2) of these, we'll have all the help pages in core done in a matter of days. And guess who it starts with? You!
If you would like to edit an existing page, simply go to the Help System group, find the page along the left, click on it, and click the edit tab.
Things to note:
- The topic titles of each module, on the left side of group page, are not listed in any order (although the modules are). The final order can be decided later.
- We are not using the drupal.org handbooks for specific styles/patterns that we need to follow for the help module's requirements. Check comments at http://groups.drupal.org/node/17287 for further information.
Comments
Using Drupal.org?
Hey Gupartap, I'm glad this is moving along! Please, please make sure you announce this kind of initiative to the documentation mailing list as well. I recognize why you are writing the docs in a wiki over here, but other than core, we also need to make sure this stuff makes it back to d.o eventually too. Is there a reason you aren't simply using d.o handbook pages for this? Everyone can edit those (and review the revisions log/diffs) and it would make incorporating the finished product much easier for everyone. :-)
Lullabot loves you
Join us at Do It With Drupal!
A large scale, curated education event
December 10-12, New Orleans
Learn Drupal online at Drupalize.me
Why fork?
I have to echo add1sun's point.
It's really critically important that documentation follows a single-source model (http://en.wikipedia.org/wiki/Single-sourcing) as much as possible. Otherwise we would very quickly get people making corrections and updates to one version and not the other and it winds up being unmanageable. It also means that anyone trying to localize the documentation is going to have to do twice as much work (translating both the drupal.org content and the help system).
I had no such intentions
I had no such intentions, nor the current setup here is meant to live after this has moved into core.
Honestly, d.o handbooks
Honestly, d.o handbooks remained out of my mind! I now really feel that this effort might be duplicate to http://drupal.org/handbook/modules, which documents(or is supposed to) features in core modules. If we are moving to those docs it'll be a lot of task to reorganize stuff the way help system needs, that should be more fun since d.o handbooks are more exposed than a definite group.
But on another thought I find wiki pages in the group useful as they are supposed to contain the topics in the exact format as is required by help module like links, etc, so that compiling them into files isn't tedious. Once this stuff moves into core, wikipages here will be buried and all the topic maintenance will be in the handbooks (where eventually all this has to move). I hope my vision isn't lousy. Awaiting feedback on this.
Will need patches eventually
Please also keep in mind that there are existing issues addressing many of these pages in the core 'user interface text' component, with discussion on these pages (and suggested revisions) that has already occurred. I think its great to get additional feedback over here by posting these pages as a wiki; we certainly need more eyes on these oft-ignored and underutilized Drupal resource. But, as add1sun said, we've also got to be able to take the output here back to d.o., likely in the form of patches to core.
I think it unlikely that the Help system patch will make it into core if it does anything other than just copy the existing embedded module help; ultimately, tweaking the content of core help will have to take the form of many patches in the issue queue. Sometimes, that tends to start the revision process over again.
But -- to me, this is a valuable effort because I recognize that not everyone follows the core issue queue. If the process over here leads to more people reviewing the text and that review leads to actionable items in the core queue, then great.
Here is one reason
Here is one difficulty in moving it to d.o. If we add any internal links or images we have to use a different url. For example in users to point people to the users list the url would be href="&base_url&admin/user/user" This wouldn't look so well in d.o. So either we need to write the documentation in d.o. and then link everything that needs linking before committing to core or we do all of it here and then remove the links before sending to d.o. I know one of Merlinofchaos's wishes was that we develop a way on d.o. to automatically build the help for the modules in the documentation pages from the help files in cvs. Kind of the same way that api.drupal.org works. Maybe wishful thinking at the moment.
Code documentation
Also note that all the hook code documentation is in core itself now: http://drupal.org/node/314870
Why only modules?
Is it possible that the Help content could be designed more to meet the user's goals and tasks rather than building it module by module?
If we only document modules, we would again wind up with strange gaps (like the lack of Theme admin help in D6) and we'd have a much less coherent organization than if we examined what it is that the user can (or should) be doing and direct him or her accordingly.
I realize that the documentation is somewhat tied to the modules, but it seems that by writing to the module, we risk losing touch with the bigger picture of what's happening in the broader UI and, more importantly, with what the user is wanting to achieve.
Yes and no
The documentation is task-based, but every task in the interface is created by one module or another. That's why we're organizing it by module.
Every task? I'm not so sure
Theme administration, clean URLs and content type creation are among the tasks that don't seem to be associated with specific modules. Shouldn't we be looking at the entire UI, rather than just going by module?
Yep, every task
theme administration and clean urls = system module
content type create = node
By module has some UX issues
The issue I think LeeHunter is concerned with is the fact that theme administration is under system module. If I'm a user looking for help with the theme system, I don't think I would look under the System section. Currently everything in the new help is broken out by module which restricts the categories. I think this is a large hurdle.
One thing we can help mitigate this is to create context sensitive help on those pages. So on the themes page in the main help listing it would be listed under system, but on admin/build/themes have links to the help files. One solution I had to this you can find here: http://drupal.org/node/300730 Basically it provides a way to add inline help topics to your pages.
Yes inline help
Inline help is the goal. the only reason we're organizing by module is so that when we turn the help pages into patches, we'll be able to know which page belongs to which module. Feel free to specify in your help page which url etc. the page shows up on.
What about admin/help?
What about admin/help? Will it still be just a list of modules? Right now, we only see "system" which doesn't really mean much to the user looking for theming etc.
This issue has actually been
This issue has actually been in concern since long and UX is the priority.
See the demo for admin/help page http://helpdemo.advantixllc.com/
We can easily override system module's help's title to say "Miscellaneous topics" which I think suits to the features it provides.
The help page is not very friendly
I like where the new help system is going, but that admin/help page does have some very serious problems.
Alphabetical order is the second worst way to organize help information (the worst would be random order). As we move down the list, we're forcing the reader to jump from one area to another (a content mgmt topic then a sys admin topic then a site building topic then another content mgmt topic then another sys admin topic etc.).
I don't see theming as a miscellaneous topic. Why have "color" (which is really an aspect of theming) as a main topic and "theming" as a miscellaneous topic. It doesn't make sense to me.
In some cases the module name does not line up with what I would be looking for. "Node" would be one example.
There is far too much information on this page and this is just showing the core modules. What would happen if I installed another 20 modules?
I would much rather land on a page that just showed the five main headings from the Admin section (content mgmt, site building, site configuration, user management and reports) each with a brief explanation of its scope ... and then click on say "content management" to see only the help that involves managing content.
I tend to cheer every time I
I tend to cheer every time I read one of Lee's posts! Partly because he tends to articulate what I'm thinking far better than I can.
There is a (very important) place for help/documentation organised by module name (it answers the question: what does this module do and how do I use it).
There is an equally important place for help/docs organised by task or topic - which is something different, e.g. answering the question "how do I do such and such" ... "how do I create a page", "what is a teaser and how do I use it" ... What about a Help link next to each item on the main admin page, a bit like on the modules admin page?
I think there is also a place for an alphabetical listing of fairly detailed topics, like the index in a (good) book. In such an index, docs for color.module might include an entry under "Color - changing theme colors" and "Themeing - changing theme colors" (pointing to the same entry).
IMO it's important to have more than one way of finding a particular piece of information. With the ability to search help as well we have all the bases covered. :)
One final thought - having the help available for un-enabled modules would also be really useful...
Sorry if some of these comments belong elsewhere.
I agree LeeHunter has
I agree LeeHunter has pointed at some bitter truth that we tend to forget with time :P "By-topic" is actually on the proposal but not in the patch yet since we haven't defined the "by-topic" skeleton to code for. The D7 soc project's module from which the patch was forked, had by-topic browsing as the default help page(but that wasn't complete either) and the by-module being optional in a tab. (similar to ?q=admin page).
That would make the help page even more cluttered!
On my final note, the current patch is the minimum structure we need to get into core before it could be further enhanced and finally opened up for everyone to improve.
I don't believe putting
I don't believe putting unenbaled modules help in the help section would be good, but I think adding the default help file to the link on the modules pages would be very helpful. But that can be an additional feature.