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
Comment #1
arianek CreditAttribution: arianek commentedtagging for review for June sprint
Comment #2
jhodgdonI 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.
Comment #3
jhodgdonSorry, my cross post removed the tag inadvertently.
Comment #4
bayousoft CreditAttribution: bayousoft commentedSomething 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.
Comment #5
jhodgdonTag 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. :)
Comment #6
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.
Comment #7
arianek CreditAttribution: arianek commentedComment #8
wmostrey CreditAttribution: wmostrey commentedI 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.
Comment #9
wmostrey CreditAttribution: wmostrey commentedComment #10
arianek CreditAttribution: arianek commentedComment #11
hansfn CreditAttribution: hansfn commentedI 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?
Comment #12
LeeHunter CreditAttribution: LeeHunter commentedComment #13
jhodgdon