Carolyn mentioned something I've been meaning to do for ages on #674474: Review and update D7 core module handbook pages, so thought I'd start an issue. We should really create a standard/template for module docs landing pages (ie. the top level page for a particular module). This would provide a consistent guideline for core, and a suggested guideline for contrib as well.

URL alias should always be: http://drupal.org/documentation/modules/[project-name] - these are all set for core modules, and I do contrib ones as I find them.

Generally it should also loosely follow what's in the Help pages since that's where a lot of the D7 content came from. So something like:

[About/Intro]

Brief intro (not sure we need to actually put this as a heading like in Help we use "About").

Uses

Use cases, and what the module's config options are - optionally divided into D7 then D6 subsections.

Configuration

Configuration instructions and options. (Could be called "Implementation" - or would that be too technical?)

Technical Specifications for Drupal 7

Eg. from Carolyn for Block module based on Ken Rickard's Field UI docs work:

Core module: Yes.
Dependencies: None.
Related Modules: Dashboard.
Permissions: Administer blocks. Also see the API docs at block permission.
API Documentation: block.admin.inc, block.api.php, block.install, block.module, block_test.module
Template files: block-admin-display-form.tpl.php, block.tpl.php
Other files: block.info, block.css, block.js
Database tables (4): block, block_role, block_custom, cache block. Also see the API docs at block schema.

Comments

arianek’s picture

arianek CreditAttribution: arianek commented

tagging for review for June sprint

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I just want to say again (as I did on a couple of comments on #674474: Review and update D7 core module handbook pages) that I am not sure this is really worth the effort. It is apparently aimed at developers (programmers I mean), but seasoned developers should be able to easily find the information in the code, and junior developers should (in my opinion) be pointed towards learning to find the information from the code.

It seems like a lot of effort to gather all this information, and it will need to be gathered again (as it will not be the same) for each future version of Drupal.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Sorry, my cross post removed the tag inadvertently.

bayousoft’s picture

bayousoft CreditAttribution: bayousoft commented

Something that is really frustrating is all the broken module documentation links from the respective project pages. Apparently a bunch are still linked to CVS? Often you don't want to download a module just to check the README.txt.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Tag went away again. :(

Also, just to clarify - on #2 I am referring only to the Technical Information section. And if it's purpose is for people other than programmers, then I will hereby rescind what I said. :)

arianek’s picture

arianek CreditAttribution: arianek commented

@bayousoft - hmm... we should maybe file an issue with webmasters queue on that? we can't really go in updating all the project pages, so not sure what we could do about it.

re: @jhodgdon's comments about the tech block - i think it's really good info to be able to see at a glance. these pages could be used by junior devs, site builders, etc. who would find it really useful to learn what all is related to a module.

we update so much other info per version, i don't really think it's so much work that it shouldn't be done at all - we don't need to do them all at once, can be an ongoing task as pages get updated, or we could do them in one fell swoop next sprint.

arianek’s picture

arianek CreditAttribution: arianek commented
Status: Active » Needs review
wmostrey’s picture

wmostrey CreditAttribution: wmostrey commented
Status: Needs review » Active

I agree with Ariane and Carolyn that, although this information can be found on api.d.o and in the code itself, ideally this information is in there. Perfect for the June sprint after #674474: Review and update D7 core module handbook pages is done.

wmostrey’s picture

wmostrey CreditAttribution: wmostrey commented
Status: Active » Needs review
arianek’s picture

arianek CreditAttribution: arianek commented
Issue tags: +Sprint: July 2011
hansfn’s picture

hansfn CreditAttribution: hansfn commented

URL alias should always be: http://drupal.org/documentation/modules/[project-name]

I think that standard for URL alias/paths makes a lot of sense and it is definitely good SEO. I plan to add such missing URL aliases whenever I find them. Any objections?

LeeHunter’s picture

LeeHunter CreditAttribution: LeeHunter commented
Issue tags: -Sprint: July 2011 +Usability
jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Component: Placement/Navigation/Structure » Policies and Procedures