Create a Way to Display Advanced Help Documentation.

Mike --

Advanced Help is a module for Drupal that other modules (such as Views) use to do their documentation. The documentation is thus shipped with the module, and someone installing Views and Advanced Help can then see the full Views documentation within their Drupal site, rather than having to visit drupal.org to see the Views handbook. That is a decision that the maintainers of some contributed modules have made, that they would rather have their documentation self-contained and maintained within their module than maintain it as a Handbook on drupal.org. We could debate whether we agree or not with that decision, but I can see why the Views maintainers wanted to do it (they now have control over the doc, so can make sure it is accurate and in sync with their code releases) (in principle, at least).

The only way to add documentation to a module using Advanced Help is for the module maintainers to add/modify files that are checked into CVS for their project. So, if you want to add documentation to that module, you would need to (a) file an issue on that module and then (b) someone would need to convert it into a "patch" and then (c) someone with CVS commit access to that module would need to commit it as a patch.

Does that clarify enough what is going on?

In other words, the module maintainers do not want the Doc team to maintain their official documentation. :)

Maybe you could take this up with the Views project maintainers? I don't think it makes sense for there to be two handbooks (one inside Views and one here).

And maybe I misunderstood your request, and what you are actually asking for is a way to display the Advanced Help doc from the Views module (and perhaps others) as a Handbook on drupal.org, not an easier way for doc maintainers to submit/edit doc for Views? To that end, I've tentatively changed the title of your issue. Thoughts?

And by the way, if you visit the Views project page, it does clearly state their point of view about Views 2 doc, down near the bottom of the page:

Views Documentation

Views 2: This link goes to the Advanced Help project page. All Views documentation is included with its installation. For your convenience, you may also visit http://views-help.doc.logrus.com. This site may or may not be fully up to date at any given time.

#4 - this is my ideal, and merlinofchaos would vastly prefer this as well.

FWIW:

1) Advanced help is searchable. It comes with its own search tool to keep those docs from getting mixed up with the general search on any site.
2) Views bugs the crap out of you to install Advanced Help. You have to go in and tell it "PLEASE STOP BOTHERING ME." (ok, really, you go under tools, hit a checkbox, and save, but still)
3) Views docs are under the same source control as the project itself. We know people want to contribute to Views docs, and that's awesome. merlinofchaos loves it when people step in and write snippets and tutorials. It's not that he doesn't want the docs team maintaining the docs - it's that he wants the docs in the same place, and he wants them right. And it's true.
4) merlinofchaos will not contribute to Views docs that are not part of the system that works with Advanced Help. "Views maintainers" are mentioned. Well, it's pretty much really "Views maintainer", singular. (Though dereine has done an awesome job helping out lately) and merlinofchaos simply does not have the time to contribute to or review docs outside of what comes through the queues.
5) Given all of the above, unless an advanced help-like system is put into place on d.o, we're guaranteeing that the docs on d.o are out of date, even if we try our very best to keep up. I don't know about you guys, but I really don't feel like copying all the docs out of advhelp, pasting them in, and then rechecking them every single time merlinofchaos puts out a new version of Views. That's even more boring than rolling comments:)

It's true. There's nothing keeping anyone from putting the docs on d.o. But it seems like a duplication of effort; effort that could be better spent doing something else. When it comes down to it, Views support ends up in the views issue queue as often as not anyway, regardless of where any of the docs are.

Maybe we should be looking at two things:

A tutorial for creating advanced help docs/patches
Exploring what it would take to get adv help onto d.o

Just as a note, someone has put quite a lot of Views 2 documentation here: http://drupal.org/node/109604 (see issue #370329: Views docs in two locations?)

And as far as module maintainers choosing to use Advanced Help meaning that doc "not being maintained by the doc team", what I should have said is "not being *directly* maintained by the doc team".

And I also want to say that I'm not necessarily against this choice. It has its pros and cons, but as a developer and module maintainer, I can see the appeal of maintaining the doc with the code and maintaining control over what goes into it!

To some degree this is a d.o issue. Ideally, d.o would be pulling the documentation from the module.

Let me state this plainly: merlinofchaos is not using cvs because he has to in order to retain control of the documentation. He is doing it because he *wants* to. He wants version control. There is no 'resorting' to cvs, as if it's something distasteful. This was a clear and deliberate choice.

Using advanced help means that *every installation* has access to the entirety of the documentationwhether or not they have access to Drupal.org. Using advanced help means the official documentation is in one place. That means that the maintainer does not have to update the internal docs and then go and make all the same changes on d.o.

If the d.o help patch hadn't collapsed, this would be so much less of an issue. Until that moves again, people are going to be better off submitting documentation patches to the modules that use advanced help.

MGParisi:

While the doc team can, in fact, choose to duplicate my documentation out from under me, I would consider it a total violation if they did. I would therefore choose to not document my modules, because I would be unable to maintain it in what I consider a reasonable manner.

If you are unable to deal with my workflow for documentation, that's too damn bad. Trying to convince the doc team to steal the documentation from me is asinine. Please stop.

I would love to see more integration on drupal.org with advanced help. The patch to put advanced help into Drupal core is stalled, however, and looks to be going nowhere. Integration with the D6 advanced help is an interesting political issue more than a software issue. Robert Douglass has already written software that can reflect advanced help documentation to pages, and vice versa.

However, one problem I have with the workflow of editing nodes for documentation is that people who edit this documentation are frequently incorrect. This is why I like the CVS revision history and patch review process. If the documentation is incorrect, it can be more easily caught. If it's not, it sits there on drupal.org and nobody does anything about it because I find that system to be unmaintainable.

Let's also add that versioning is a major issue. Views 2 and Views 1 are very, very different. Having the docs completely separated is a good thing. I do not like having the Drupal 5 and Drupal 6 handbooks merging across each other, it is bad User Experience, even if it is more work to maintain.

Finally: it's my project. I appreciate suggestions and criticism, but I do not appreciate being told how to run the project by someone who hasn't taken the time to understand why things are set up the way they are.

Oh, finally, because drupal.org is not capable of reflecting advanced help at this time, I maintain my own copy of the advanced help on the web. It's very easy to find. It is totally googlable.

If someone from the doc team wants to review that Views 2 doc for stuff that should be in the advanced help, I'd appreciate issues being posted. I'm willing to take html docs rather than patches for stuff that should be new docs. This is particularly true for new tutorials, of which I am happy to expand beyond the 4 tutorials we have now, particularly for tutorials that demonstrate functionality that is not currently demonstrated. The tutorials are the best user documentation we have, so well written tutorials are a boon.

Will do (review Views 2 doc and post issues to Views queue). I think it makes sense to have a short intro to what Views 2 does in the Contributed Modules section of drupal.org, so that people can use that to make decisions on whether Views might serve their needs. But I agree we'll take the How To doc out of the handbook (archive), and file issues as appropriate to add their information to the Advanced Help within Views.

Related issues:
#370329: Views docs in two locations?
#395076: Intro to views 2
#495418: Contrib module information architecture ideas

I'm going to close this as a duplicate of #495418: Contrib module information architecture ideas, which has a more comprehensive picture of information architecture and documentation for contributed modules. I think the other issues brought up here have already been addressed.