Views docs in two locations?

Hm, yeah, we definitely want these merged. You may want to check with merlinofchoas before moving the top-level book, since I'm not sure what his thoughts/reasoning were, other than making it easier to get to for people who know about d.o/book. ;-)

I had a very small chat with merlinofchaos yesterday on IRC. I asked him about this and basically its about navigation. When the top-level book was created a few years ago, the docs people agreed on it. Now, he said it doesn't matter regarding Views 2 but there's extensive documentation on Views 1 on the top-level book which will be difficult to navigate thru if merged to the present http://drupal.org/handbook/modules/views. In this particular case, I agree that the docs are too extensive and the navigation block becomes useless.

I think there is a bigger issue here - on organizing modules' docs. It is diificult for users to have an overview of a particular module when the documentation becomes big and complicated. IMHO, we need to come up with a more general solution in dealing with contributed modules' docs.

A live example of the usability problem I mentioned above is CCK . It has its "Content Construction Kit Handbook" as a subsection of d.o/handbook/modules/cck. If a user is in http://drupal.org/node/110512 there is no way for that user to know where he really is in the module's documentation. The "up" link does not help because the parent page (http://drupal.org/node/89493) is still on a level hidden in the book navigation block. The breadcrumb is also useless because it is too long and already hidden under the search field.

If we move the Views docs under d.o/handbook/modules/views, we will have the same problem. Also, Views is near the bottom of the navigation block, that the plethora of modules becomes too daunting and disconcerting.

I agree 110% that contrib module's docs should be merged in one place but there is a usability problem we should address due to the present setup and tools we have. We can probably inform merlinfochaos and merge the Views docs to the right place but personally, I would also like to hijack this issue, change the title and turn it into a bug report so we can discuss the possibility of fixing this problem.

Lets get the views 1 documentation in Archive...

Then lets move the views 2 documentation in the http://drupal.org/node/109604 into the modules sections. Lets place it in places the best we can. Then we will re-write it and combine the pages as needed.

However this is for d5, and though its valid documentation, and I am still running d5, people using D5 probably already know how to use views. Lets focus our efforts on D6 documentation.

The questions regarding views 2 are almost non-existent... so lets not spend too much time on this!

I will take responsibility as long as no one disagree's

As far as the over-all issue, I think it is a valid issue that desirves its own queue.

Speaking from the perspective of someone who's supported software for way longer than anyone ever should:

It's a *really* bad idea to archive documentation on a version that is still supported. Views 1 may not be getting a lot of love (though there's a couple of people who are doing some awesome helpfulness in the queue), but Drupal 5 *is* still supported, and Views 1 is the only one available for D5. If a version is still supported, you need to leave docs where people expect to find them. Just because you can find it and don't need it doesn't mean that's the case for everyone. I promise you.

People who are using D5 for whatever reason that go looking for the docs aren't going to find them if they're in Archive, and that's going to cause the issue queue to go nuts.

I will unequivocally state that if anyone does something that increases the Views issue queue, I will have to bring my rubber crowbar to the next drupalcon and beat you with it. Alternately, I will go through the queue and assign every single "Where are the docs" questions to you. It depends on how angry merlinofchaos gets :)

As for the Views 2 docs - the official Views 2 docs are in Advanced Help. There are *plenty* of questions in the Views queue. The tips, tricks, and tutorials definitely need to be out and easily accessible, but we need to make every effort to not duplicate the official docs that are there. merlinofchaos is not going to maintain them unless d.o starts pulling from advanced help, or there's something that takes its place.

And my intention, once the book is done is to come visit all the views and panels docs pages and try to perform a thorough cleanup. With any luck, I'll actually be *able* to do that, but that's at least a couple of months out. So if you want to take a whack at them now, that's cool. I'll just pass over it again later!

Opps, yea, I got the version's wrong. I agree, Views 1 Docs should not be Archived.

I would be willing to work on Views 2 Docs. But were do we want them, in the handbook or in its own book? With unlimited resources I would love to work on D5 documentation. The problem is that my heart and my limited time both push me towards D6 topics. Maybe we can have a mini-sprint as we had this morning (its 11:55pm here)

As far as crow bars and Druplicon... I think I need someone to buy me a ticket so you can beat me over the head!

I think it could be beneficial for every module to have its own book. That book is then tied to that module and is maintained by the users of that modules (as well as us). I am always for centralizing data around content. The current setup does not support this. Currently documentation is pushed into this huge contributed modules page. I agree on the larger issue, and think having documents based on modules should be centralized around the modules. I have some ideas on this however isn't this out of scope from the original issue?

So what we need to do is:

a) Make sure the Views 1 documentation is all in one place. What I would suggest is using the top-level handbook: http://drupal.org/node/109604 and moving relevant pages from that other section over there, as appropriate.

b) We also need to archive the Views 2 documentation in the handbook, and instead point people towards using Advanced Help within Views, and towards Merlin's site that displays this advanced help (see link on Views project page). This is the only official and maintained source for Views 2 documentation. But before we archive each page, it would be good (Merlin suggested it) (Merlin being the Views maintainer), someone should review each page to see if what the page offers should be added to the advanced help inside Views. This is a fairly large project, but I do think it should be done.

c) http://drupal.org/handbook/modules/views should be a short page pointing to the Views Handbook for Views 1 and the Advanced Help within Views 2, once those sub-pages have been moved into the top-level views handbook.

MGParisi you assigned yourself to this issue, do you still have any interest in taking it on?

See http://drupal.org/node/492210#comment-1714204 for the Views maintainer's take on Handbook doc for Views 2. Summary as in (b) above.

Also, check this discussion #395076: Intro to views 2. Probably it would be good to have a short overview of Views 2 in the handbook, telling what it does, rather than how to do it (we should leave the "how to" discussions to Advanced Help within Views).

I have added a small amount of description of the module to http://drupal.org/handbook/modules/views as well as http://drupal.org/node/109604 and http://drupal.org/node/395064

I also moved a bunch of pages around... There are now only sub-module pages in the main handbook under Views, and mostly only Views 1.x docs in the top-level Views handbook. I archived a bunch of Views 2.x pages that were covered well in Advanced Help or the Views API documentation, and reorganized some others.

I also filed a bunch of issues in Views to move some good tutorials into Advanced Help, and put all of these into a new "unofficial views 2 tutorials" section within the Views handbook. Each has a link to the corresponding issue. I am unsure how those issues will be treated... we'll see... anyway, the tutorials are still around in case someone wants to look at them in the meantime.

So, I think this issue is taken care of. Feel free to differ. :)