Closed (fixed)
Project:
Node Gallery
Version:
6.x-3.x-dev
Component:
Documentation
Priority:
Normal
Category:
Task
Assigned:
Unassigned
Reporter:
Created:
30 Nov 2010 at 20:50 UTC
Updated:
19 Jul 2011 at 05:21 UTC
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.
What's the user community's thoughts?
Comments
Comment #1
scroogie commentedMhm, 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?
Comment #2
justintime commentedI 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.
Comment #3
scroogie commentedI'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.
Comment #4
justintime commentedLet'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?
Comment #5
scroogie commentedOk, alright then.
Comment #6
scroogie commentedI 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.
Comment #7
dddave commentedShould 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).
Comment #8
justintime commented@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.
Comment #9
justintime commentedIn the interest of getting what we have already out in front of people, I took what we had for advanced_help, and committed it.
Comment #10
justintime commentedWell, 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.