Since we have no documentation for 3.x yet, now is the time to make this decision.

No matter what, we'll use hook_help() for form-specific help, and a very basic overview of things.

However, we need something that provides for a FAQ/Recipe Collection, and more verbose documentation on how things work and how you can tweak them.

I'm torn between integrating with advanced_help, or using D.O handbook.

  • D.O Handbook
    • Pros:
      • Anyone can pitch in
      • Anyone with a browser can read it
    • Cons:
      • Usually no one but the original author does pitch in
      • People leave comments on book pages for support when they should use the issue queue
      • Book module and input filters can be limiting on the style of documentation
  • advanced_help
    • Pros:
      • Looks like it's easy for translators to translate.
      • No need to keep separate versions of the handbook for 2.x vs 3.x - the docs are included in the module
      • It's free-form HTML, not constrained to the book module and D.O's input filters.
    • Cons:
      • Requires another module to be installed in order for the user to use the docs. (Although we require views, and views has a nag screen when it's not installed)
      • Requires that you install node_gallery before you can read the docs. We could probably link over to the demo site's advanced help from the project homepage though.

What's the user community's thoughts?

Comments

scroogie’s picture

Mhm, good question. Both have advantages and disadvantages. advanced_help looks attractive to me, but if we indeed have volunteers, it would be good to include them. Perhaps we can have the best of both worlds, by allowing to write documentation on our demo site (using automatic revisions of course) and exporting it now and then?

justintime’s picture

I spent some time doing some research, and I'm starting to think that using the Drupal Handbook would be the best opportunity here for a few reasons.

1) I think advanced_help is more for people writing internal module help/docs (i.e. proprietary modules not on D.O). However, I have no idea why Views chose advanced_help.
2) If we want collaboration, we get it for free.
3) We don't have to maintain the demo site.
4) Perhaps the most significant reason - the documentation team seems to have a lot of motivation as of late. We have new documentation team leads in place, and a list of things they're working on: http://drupal.org/community-initiatives/documentation. It looks like once docs.drupal.org launches, we can attach videos and do a lot of other nice things as well.

scroogie’s picture

I'm not really decided. I'm waiting for you to make the decision. :)

That said, I'd like to explain my current impression. As you have probably seen through the dropbox invitation, I played around with advanced_help and created a few pages. What I really like about it, is that you make the help accessible from where it's needed. Exactly when the user faces the problem. advanced_help supports that with it's popups and links. You can put your links in a way that users can click a question mark when they're on the manage images page, to arrive at the manage images help in a quick and easy way, without leaving their page. I think this is really the biggest advantage of advanced_help. The help is part of your module, so you can include it everywhere you like. On the other hand, the strong point of the handbook pages is in my opinion the collaborative nature, and, not to underestimate, it's dissemination effect. So in an ideal world, I think *every* module would have both. The advanced help that explains the user interface, workflows, and recipes how you can exploit the module directly in the drupal interface, and a handbook that is really like a handbook, explaining background, API, code snippets, theming, and so on. Of course, that is a whole lot of work. Just my 2 cents.

justintime’s picture

Let's go with advanced_help. There's pros and cons a mile long, but I think the inline functionality is a big win. There's a few users I can think of that are good with this kind of thing, and I think we can just share the Dropbox folder with them. Dropbox has built in versioning too. We can then just pull the Dropbox contents into CVS as needed. Once complete, it shouldn't be too hard to create handbook pages on d.o should we need it.

I'll open up the advanced help on the demo site too, and link to it from the project page, allowing Google and users who don't have it installed yet to peruse it.

Sound good?

scroogie’s picture

Ok, alright then.

scroogie’s picture

I finished a preliminary about page and recipes section that covers some common topics. I created stubs for the submodules. The current revision is in Dropbox. Perhaps it will need a language review of a native speaker.
The rest remains to be written. With the "Create a gallery" page we could wait to see what comes out of #996978: NG3 workflow improvements.

dddave’s picture

Should we use a tag for things we want to add to the advanced help? Or do we consider all issues filed under the documentation component to be included?

I would prefer a tag like "Needs advanced help coverage" (verbose, I know).

justintime’s picture

@dddave - knock yourself out :) However, it looks like there's already an 'advanced help' tag. Completely up to you - personally I don't use the tags on issues so it doesn't matter to me either way.

justintime’s picture

In the interest of getting what we have already out in front of people, I took what we had for advanced_help, and committed it.

justintime’s picture

Status: Active » Fixed

Well, we're almost done with advanced_help integration, so let's stick with that. :)

There will be a section in our help that will be named "Advanced Topics". Aside from listing some of the "top offenders", I'll include a link to the issue queue that will search for all topics with the component of Howto/FAQ/Example.

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.