handbook - module location cheat sheet (landing page)

I would recommend putting that information here: http://drupal.org/node/628280.

It used to be that all the contrib modules were together in one list, which was handy for the writers because you knew where to put your documentation. But putting thousands of modules together, in no particular order, wasn't quite workable especially since the reader really just wants to know how to get stuff done and doesn't care much whether it involves core or contrib.

So the docs have been restructured into a role and task-oriented approach which is pretty much the standard for software documentation. For example, there's now an administration guide for people who do the day to day operation of an existing site. Any contrib modules that help with administration should go in the admin guide.

This can be a little confusing because words like "administration" are fuzzy concepts. Some people think of administration as pretty much everything - installation, design, coding, IA etc.

I think the doc landing page (http://drupal.org/handbooks) does a reasonable job of explaining what goes where. It could certainly be improved but it's probably not possible to cover every case (while still being easy to scan).

Yeah I think that would be useful but I'm not totally sure that it's the sort of thing that should be done manually. What's really desperately needed, on top of the current IA, is a tagging+Views implementation so that people can filter and sort the documentation from all sorts of different perspectives.

yeah, joachim we've been talking about this off and on, it is pretty confusing if you just want to find a specific module... i think a landing page or tagging system will eventually solve things, but it may not happen until we overhaul the docs section. will see.

i'm seeing there's already a section for that module here: http://drupal.org/node/696210 it would be best to stick with one main page for the module, and then link to it from the other section (ie. profiles vs. taxo)

if you would like a url aliased to /handbook/modules/user_terms just post the node id here and we'll get it set up.

aha, i did not realize you made the page.

i see that you are asking for a cheatsheet for module devs, and sure, that would be a fine thing to have, but with the amount of work it would take to find all the different sections and list them, we're just as well off creating the proper landing page (also a sort of cheatsheet, apart from the main /handbook page) that would list out where the different modules are, grouped by task.

otherwise we're kind of duplicating efforts.

well.... sort of? i don't know the history of how it used to be organized. but the current way it's organized is how Lee's been working on sorting it into sections of related topics. ie. instead of all the core modules being in one section, core and contrib are all split up by image handling, file management, etc. etc.

i fully realize it's not very intuitive for us - i brought this same issue up (and if we were to start from scratch, i think there might be better solutions). that said, i understand the rationale for organizing it this way, as end users who are not as familiar with how things work code/module wise will find it a lot more useful to see topics lumped together.

if i can't find a specific module page by browsing, i usually type in the URL of a module i think is in the same section, and go from there. (and again, totally realize this is far from ideal)

all that said - YES, great, let's have a cheatsheet/landing page. i've changed the issue title to reflect this task. what i would suggest is making a list of all core modules with their urls, followed by a general list of the different topic areas and which contrib/core modules are found in them (with urls).

BUT fwiw this is lowish on the priority list of the docs team right now - D7 docs are waaaay behind, so unless someone adopts this task, it may be a while.

Taking the example of the user terms module, you just have to look at the doc landing page.

Only three books - Administration Guide, Structure Guide and Site Building Guide - are at all likely candidates.

And right there, in the description of the Structure Guide, it specifically mentions that it covers taxonomy.

If you open the Structure Guide one of the major headings is Working With User Profile Information.

You're asking for some kind of a guide but it's already right there on the landing page.

I really don't see the point of keeping a separate list of where every module might be located because it would be impossible to keep up to date and structuring the docs by roles and tasks is really the only sane way of dealing with a massive documentation set serving different types of users with many different objectives.

It may not be ideal from the viewpoint of the module developer who just wants to know "where do I put my stuff" but the docs are really there for the user to get stuff done. Sometimes a task involves contrib modules, sometimes core, sometimes both but you have to start with what the user wants to do, not with Drupal's inward-facing distinction between x and y technology.

just said this on the thread you linked to, but repeating here fwiw: if you can let me know what the module does i can try and help sort where it should be. pls follow up there if i can help.

==

i'm leaving this critical, but marking it postponed, because there are much more critical issues that need addressing, and about 3 people actively working on docs right now, so this unfortunately this can't take priority.

i think for now, we will have to do with setting url aliases for contrib modules to match the project url's ie. http://drupal.org/handbook/modules/[modulename] is for http://drupal.org/project/[modulename] and using google.

not trying to be dismissive at all, but we just don't have the resources to manage this within the docs team, at least until d7 is out and docs are up to date for it. http://docs.drupal.org is soon to be launched (we are next on the docket for redesign completion as far as i know). once we have docs.d.o, we will have a lot more power to take action on these long standing issues and create smart solutions for them.

The best option for a cheat sheet would simply be a page that shows an expanded master table of contents for all guides. In other words, so you don't just see the titles of the guides but also the section headings. Even better would be an option to expand sections of the master ToC to show individual page titles. It would be a fairly long page, but at least you could search or skim down to find the right spot.

I don't think it's a good idea to create a manual cheat sheet. It would probably become outdated very quickly.

Trying to understand what's needed here. As I see a few different suggestions.

Problem: no idea where to put new module documentation.

Suggestions:

A) handbook - module location cheat sheet (landing page) (#0: issue title)
B) a page on writing module documentation (#19)
C) a page that shows an expanded master table of contents for all guides (#18)

Also trying to get an idea of the meta problems. Mentioned are Requirements:

1) on top of the current IA, ... a tagging+Views implementation (#5)
2) role and task-oriented approach (#3), documentation has to be task-based for the benefit of users. (#13)
3) a need to also have a way into it that is a straight index -- because sometimes as a developer you know you want to read about contrib module X. (#13)

Could you sum up what is required?

In addition to my question above: perhaps it would be a good idea to have correspondence with the module overview page (/admin/modules) or the configuration page (/admin/configure) in core. Off course there is no consensus on that and every module maker makes up where he/she thinks the module belongs. I'm sure it is the same confusion they are confronted with when trying to figure out where to put their documentation. Lot's of modules and themes link to a page outside of drupal.org to place their documentation.

It would take writing guidelines with which module developers can make a decision where to put their module's documentation. And writing that guideline would take some consensus about the categories.

Currently used on the admin/config page, which is the most structured overview page in Drupal 7:

People
System
Content Authoring
User interface
Media
Development
Search and metadata
Webservices
Regional and language

Some modules, like Rules, put their module in a separate category, in this case "Workflow". And now I come to think of it, Views isn't listed on that page at all. It's located at /admin/structure/views/settings.

Perhaps the structure of the admin menu should be taken as a guidline?

As modules grow more and more in the direction pieces of a framework (specific solutions for a small function rather then general solutions for a very specific usecase), putting them in categories may become harder.

This is about the structure of the book style documentation, which is deprecated.