[drupal-docs] [task] How to understand a module so you can document
it
cel4145
drupal-docs at drupal.org
Thu Sep 1 00:06:59 UTC 2005
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: cel4145
Status: active
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).
cel4145
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.
------------------------------------------------------------------------
Wed, 31 Aug 2005 16:17:14 +0000 : Amazon
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
------------------------------------------------------------------------
Wed, 31 Aug 2005 16:50:17 +0000 : webchick
> 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.
More information about the drupal-docs
mailing list