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 commented

tagging for review for June sprint

jhodgdon’s picture

jhodgdon
she/her
Primary language English
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
commented

Sorry, my cross post removed the tag inadvertently.

bayousoft’s picture

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
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 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 commented
Status: Active » Needs review
wmostrey’s picture

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 commented
Status: Active » Needs review
arianek’s picture

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

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 commented
Issue tags: -Sprint: July 2011 +Usability
jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Component: Placement/Navigation/Structure » Policies and Procedures
quietone’s picture

quietone commented
Status: Needs review » Postponed (maintainer needs more info)

I think it is time to check in here an find out if there is any community support for the ideas in the issue summary.

avpaderno’s picture

avpaderno
he/him
Primary language Italian
Location Brescia, 🇮🇹 🇪🇺
commented

I think that we should use http://drupal.org/documentation/modules/[project-name] as path alias for a module's documentation page. It would avoid going to the project page and clicking on the documentation link given there.

hansfn’s picture

hansfn commented

The only change since I last supported this 12 years ago is an S (and "documentation" = "docs"):

httpS://drupal.org/docs/modules/[project-name]

And the current URL for these pages are:

https://www.drupal.org/docs/extending-drupal/contributed-modules/contributed-module-documentation/[project-name]

which is terrible, and depends on me making sure people create doc guides with titles that match the project name. (I have discussed all of this other places.)

quietone’s picture

quietone commented

Is creating those URLs something for the drupal.org customization project?