[drupal-docs] [task] How to understand a module so you can document it

[Amazon]

Issue status update for 
http://drupal.org/node/30049
Post a follow up: 
http://drupal.org/project/comments/add/30049

 Project:      Documentation
 Version:      <none>
 Component:    Admin Guide
 Category:     tasks
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  Amazon
 Updated by:   Amazon
 Status:       active

I added [Optional for programmers] to the line about reading the code.


http://drupal.org/handbook/modules
At the bottom of the list of modules there is a single link to the
contributed modules.  I was suggest only the link be moved to the top
of the page, not a link to every contributed module.


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


Cheers,
Kieran




Amazon



Previous comments:
------------------------------------------------------------------------

Tue, 30 Aug 2005 21:14:47 +0000 : Amazon

http://drupal.org/node/30048




------------------------------------------------------------------------

Tue, 30 Aug 2005 22:25:49 +0000 : Bèr Kessels

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




------------------------------------------------------------------------

Wed, 31 Aug 2005 00:53:11 +0000 : webchick

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.




------------------------------------------------------------------------

Wed, 31 Aug 2005 01:32:05 +0000 : Amazon

First off, thanks for your help.


1.  Here's the contributed modules:
http://drupal.org/handbook/config/contribmodules
2. Is there any sort of template we should follow? For example:
- Module name-  Done
- Maintainer-  That's available in the project, I am proposing the
addition of a link to submit an issue.  Otherwise maintainer is in the
project.
- Module project page link-  This is better than maintainer, IMO.
- Dependencies (both "hard" dependencies and also other modules that
enhance this module in some way)- It's wanted but a lot of work.
- Description (what does the module do generally?) -that's the first
paragraph of Admin help.
- Usage examples (why would I actually want to use it?)-  That's what
the child pages are for.  But we haven't got a lot of submissions.
- Installation instructions (if there's anything special you need to do
other than the norm)-  That's in the INSTALL.TXT
- Setting permissions (what permissions exist and what they do)-  I am
ambivalent, but it could be useful.  I link to access control would be
good.
- Usage instructions (common tasks and how to perform them - this could
potentially be quite long, depending on the module)-Well the idea is the
second paragraph is common tasks.  The "you can" section is context
sensitve links to show you want you can do.
- Notes (misc. points of interest, user submitted tidbits, etc.)-Good
for child pages.


There is already some attempts to make this work.


3.  We have agreed to single source the documentation for the code in
the handbook and extract from there.  Does that answer your question?




------------------------------------------------------------------------

Wed, 31 Aug 2005 02:31:35 +0000 : webchick

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.).




------------------------------------------------------------------------

Wed, 31 Aug 2005 02:37:45 +0000 : Amazon

I just didn't scroll down far enough to see the contrib modules section!



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


Kieran




------------------------------------------------------------------------

Wed, 31 Aug 2005 02:51:26 +0000 : webchick

> 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?"




------------------------------------------------------------------------

Wed, 31 Aug 2005 02:52:39 +0000 : webchick

"...we eventually get to the point where all contrib modules (or even
most) are downloaded..."




------------------------------------------------------------------------

Wed, 31 Aug 2005 02:53:27 +0000 : webchick

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




------------------------------------------------------------------------

Wed, 31 Aug 2005 05:52:46 +0000 : cel4145

+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.