Closed (fixed)
Project:
Documentation
Component:
New documentation
Priority:
Normal
Category:
Task
Assigned:
Unassigned
Reporter:
Created:
8 Mar 2009 at 09:46 UTC
Updated:
3 Jul 2009 at 21:50 UTC
Views 1 had a brief introductory page with an overview of the module, and several child pages going over each aspect.
For consistency's sake, I created a similar introductory page for Views 2. However, the only bit of documentation I found was "go see Advanced Help."
A brief overview of views 2 should be added -- a screenshot of the output of a simple view and a screenshot of the admin interface would probably be a good idea. Additionally, the child pages from the Views 1 documentation should be evaluated to see what can be duplicated and/or modified under the new Views 2 documentation. I think it makes sense to have separate pages, even if the content in each is identical, so that all the Views 2 docs are in one place and people don't have to go back to Views 1 docs to find out what it is.
Finally, it would probably make sense to end that section with a child page on comparisons between Views 1 and 2.
I'm hoping to do some of these tasks, but I thought I'd add it to the issue queue in case anyone else wanted to work on it.
Comments
Comment #1
rootworkA lot can be taken from this wiki page on g.d.o.
Comment #2
jhodgdonFor Views 2, the project maintainers have decided that all documentation is maintained inside the Views module itself, via Advanced Help. So we should not be maintaining handbooks on drupal.org for Views 2.
If you think your handbook page and wiki page mentioned here contain information that is missing in the Advanced Help within Views 2, please file an issue with the Views project http://drupal.org/project/issues/views
Thanks!
Comment #3
rootworkI know that's Earl's wish, and I think it definitely makes sense to fully and prominently link to the views documentation within Advanced Help. But if you look at the views handbook area, there's already quite a bit of documentation, how-tos, examples, snippets, etc. Are we really going to delete all of that? Ban it from existing on d.o? I don't think it's unreasonable to say "official documentation is over here," but I think it's going to be fighting a losing battle to keep any and all Views 2 documentation off the site.
That said, I think it's great that the docs from Advanced Help are available at that mirror. But wouldn't the more logical place for that mirror be...d.o?
Moreover, the Views 1 documentation does a fairly simple job of explaining what views is. I think at a minimum, we should have that sort of explanation here. Saying "you can't even know about what views does unless you install Advanced Help and Views and then read these docs" seems a little outlandish.
So I would suggest an introduction stating something like the following:
1. Here are three sentences about what Views does and why you would want to use it. This could be copied verbatim from the project page.
2. Full, official, complete documentation is available via Advanced Help.
3. That documentation can also be found here (presently at the mirror; eventually, I would hope, on d.o itself).
4. In addition to that official, complete documentation that you should read before you proceed with any of the following, here are some contributed guides, tips, how-tos and snippets. Use at your own risk.
What do you think about that?
Comment #4
jhodgdonYes, the proposal is to move most of that documentation into Advanced Help. I agree having a small introduction on d.o makes sense -- having some "what is Views" is good; the main thing to avoid is the "how to do xyz in views" and get that into Advanced Help.
We have another discussion going about getting the Advanced Help mirrored on d.o., but it's not there yet.
Two other issues where this is being discussed:
#370329: Views docs in two locations?
#492210: Create a Way to Display Advanced Help Documentation.
Comment #5
rootworkCool, I'm glad to hear there's talk about getting the mirror on d.o.
But I still disagree with the idea of trying to keep off the "how to do xyz in views" from d.o. I just don't see the harm in having "official" documentation (with big arrows and flashing text if need be) and user-contributed documentation. Isn't that what d.o handbooks are all about? Are we really going to be policing the handbooks for anything mentioning views 2? Why would we spend our time doing that?
Comment #6
jhodgdonAll of the modules on drupal.org, including Views, are maintained by volunteers through contributions from the community. For some, the community can contribute documentation by adding/editing Handbook pages on drupal.org. For Views, the module maintainer would like contributors to submit their doc for addition to the Advanced Help within Views. So if there is something missing from Advanced Help, the maintainer of Views has asked that it be submitted for inclusion in the Views project, rather than making doc pages in drupal.org. See http://drupal.org/node/492210#comment-1714204 -- this is a comment he wrote in the last day or two on this exact subject.
The main ideas are to have all the documentation in one place, so no one has to bounce back and forth to find answers to their questions, tutorials, examples, etc., and to make sure the doc is accurate.
Comment #7
jhodgdonComment #8
jhodgdonI 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. :)
Comment #9
rootworkI think this is great! Good way of directing new folks to how to contribute it to Advanced Help. I've left a comment on the Views 2 theming issue and would be happy to help get that into Advanced Help.