How to understand a module so you can document it

so, the post seems fine. what about this issue. close it?

Hm. A couple things I see missing from this document, as someone who is new to writing Drupal documentation--apologies in advance if these are really "duh":

1. Where does module documentation actually go? The logical place would be under http://drupal.org/handbook/modules, but that seems focused solely around core modules (which is not a bad thing--if every single contrib module gets documented (which it sounds like is the plan), this list would become too cumbersome to use after a very short period of time).

2. Is there any sort of template we should follow? For example:

- Module name
- Maintainer
- Module project page link
- Dependencies (both "hard" dependencies and also other modules that enhance this module in some way)
- Description (what does the module do generally?)
- Usage examples (why would I actually want to use it?)
- Installation instructions (if there's anything special you need to do other than the norm)
- Setting permissions (what permissions exist and what they do)
- Usage instructions (common tasks and how to perform them - this could potentially be quite long, depending on the module)
- Notes (misc. points of interest, user submitted tidbits, etc.)

This might be WAY too much or way not enough, but it seems like there would be value in standardizing the handbook documentation on modules to some extent.

3. Is this even the type of thing that this documentation is intended to cover? Or are we strictly talking about submitting documentation patches to existing projects? This might actually be a better approach because then it's all right there rather than having to look at the handbook (if applicable), the stuff in admin > help (if applicable), AND the files that come with the module (if applicable) to figure out how to use it.

Thank you, Amazon, that answers all of my questions. Sorry about that--I just didn't scroll down far enough to see the contrib modules section! I've spent some time looking at more of the contrib module pages that are there and you're absolutely right--for the most part, they do all follow the same general way, and the stuff that's not there makes sense for not being there (install instructions, etc.).

> Any other ideas for how to make this more obvious. Should we move contributions to the top of the list?

Perhaps have it at its own top-level node alongside "Blocks," "End User Guide," etc. Maybe "Drupal modules and features" and "Additional modules and features" (wording could maybe be better...)? This way you can collapse the default installed ones when you're done reading about that and only focus on the modules that you can add to Drupal beyond what's included by default.

I realize it's kind of counter-intuitive; from a hierarchical organizational standpoint, it makes perfect sense to "keep all modules together." But if you move the list of contrib modules above the core modules, and we eventually get to the point where all contrib modules (or even most) are downloaded, it'll be a full 6-8 page scroll before you can find out "what does taxonomy do?"

"...we eventually get to the point where all contrib modules (or even most) are downloaded..." << should be documented, sorry.

AHEM. "downloaded" should be "documented." Sorry for the spam--preview doesn't seem to be working. :(

+1 to what webchick has says about moving the location of the contrib module docs in the handbook structure.

Also, as someone who can read code just a little (although I have not coded anythying significantly in 18 years), I think the advice on reading the module code is easy to say for a coder, but not realistically practical for non-coders. So while you don't need to be a php programmer, you do need to be able to read code, IMHO. I'd offer it as an optional note for coders at the bottom of the page so we don't scare potential contributors away.

> The list would stay the same length, but the link to contributed more
> would be more prominent.

Right, but here's the problem with that...

At 800x600 (I know no one runs crusty ol' 800x600 anymore, but humour me ;)), when I just click on "Drupal modules and features," I have 5 page downs before I hit the bottom of the list. This is just for core modules.

When I click "Contributed modules," that now adds an additional 6 page downs, and that's with only probably 10% of the contrib modules having a menu entry there. This will only increase dramatically as we add more documentation for this section. This is because "Contributed modules" is a sub-chapter of "Drupal modules and features."

So if this extra 6+ page-downs worth of information is placed *before* the core modules, I'm never in my life going to get to the information I need.

I think you're saying don't move the *entire* "Contributed modules" section up to the top of the list, but merely a link that takes you to http://drupal.org/handbook/config/contribmodules. And that would be fine, except I *still* have to scroll down 6+ times every time I want to click on a different contrib module, even if I'm already done reading about core modules and only want to focus on the contrib stuff. This is why I would suggest moving the Contributed modules section to a chapter of its own right, after "Drupal modules and features." But maybe the link at the top of the core module list would be all that's needed, and from there people could hit "back" to navigate from the main jump-off page rather than using the links on the side.

To add to what webchick said, I'd suggest renaming the one section "Core modules" and the other "Contributed modules." Modify the first page of the former to make it clear that the following are modules included with the core Drupal download linking to the download page, and the latter with similar explanation about contributed modules. Of course, keeping each explanation down to one sentence so that webchick won't have to scroll too much ;)

I'd also consider moving the "Blocks" section into the blocks.module section (where it seems to logically belong).

Or probably "Modules" and "Contributed modules"--Drupal seems redundant.

As for the blocks, I was pointing out that it currently *is* in two places. Makes sense to move the main Block area that is listed at the top level of this book under the block.module listing, doesn't it?

If I am reading this thread right, the suggestion is for modules and contrib modules be two separate sections instead of one under the other.... which hasn't been done, does that mean it won't be?

Also, the modules page doesn't make it clear the difference between core and contributed.

'Modules listed here are included with your Drupal installation. Contributed modules are 3rd party modules and are not included. You must download them from...linky.'

http://drupal.org/handbook/modules

Anisa.

Documentation is now available for both Contributed and Core modules. Closing this task.