>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #495418. --> Reported by: [jhodgdon](https://www.drupal.org/user/155601) >>> <p>Here is a thought about contrib module documentation architecture, for the in-progress overhaul of documentation. I'm filing this issue for discussion of the ideas; suggest we get the goals agreed to first, then think about how to implement them.</p> <p>Contrib modules have several ways to provide documentation to their users, beyond the minimal amount normally found on the project page. Module maintainers can pick and choose between these methods, depending on their preferences:<br> - Advanced Help or standard Help within the module distribution (available only when the module is installed/enabled)<br> - README.txt, INSTALL.txt, and other .txt files distributed with the module (readable before the module is installed)<br> - Handbook pages on drupal.org<br> - Outside web sites (most common with third-party-integration modules)<br> - API documentation embedded in the code and/or separate .api.php files<br> - Forums, issue queues, and groups</p> <p>In my opinion, all of these types of documentation have things to recommend them, and I don't think we should try to dictate which methods a particular module should use. However, currently only Handbook pages are readily available for viewing and locating within the Handbook section of drupal.org, and links from the Project page to the above are mostly rather ad-hoc. So it would be good, as we consider frameworks and information architecture for the doc on drupal.org, to provide methods for modules to have all of their documentation available, locatable, and integrated, rather than having to duplicate information or maintain external sites to display information.</p> <p>Ideally, each module maintainer should have the ability to:<br> - Designate "This module has an API for other modules to use that should be extracted from these files" (or we could just extract everything from modules, maybe onto contribapi.drupal.org or something like that -- in my opinion, this is fine to be on a separate site, since developers are already used to api.drupal.org and API doc is not really "handbook" material anyway)<br> - Designate Help or Advanced Help that should be extracted and displayed -- maybe we could have another site, like modulehelp.drupal.org that would display this for all modules?<br> - Select which .txt files from the module's CVS repository are documentation that should be displayed (not all are necessarily important to display as "documentation").<br> - Designate which is the main Handbook page for the module (this sort of exists now -- in the Resources section, you can put in a link to "documentation", but it's not specific to Handbook pages)<br> - Add links to one or more external documentation resources (URL and link name, maybe short description as well).<br> - Designate forum section(s) and/or group(s) on groups.drupal.org that are related to the module. We might need the reverse as well: the ability to designate that a forum section or group is related to a particular module, so it can link back.<br> - Designate an issue queue for the module (we can do that now).<br> - Designate a CVS repository for the module (we can do that now, not sure how obvious it is how to browse it though).<br> - Place a module in a well-designed taxonomy hierarchy. Currently, the project category taxonomy is lame -- it leads to a truly unworkable navigation on <a href="http://drupal.org/project/modules">http://drupal.org/project/modules</a> -- it is downright impossible to find modules there. The navigation to find contrib modules at <a href="http://drupal.org/handbook/config/contribmodules">http://drupal.org/handbook/config/contribmodules</a> is somewhat better (at least the categories somewhat make sense; could possibly be improved, but it's a better start at a taxonomy, and yes I realize it is not a Drupal Taxonomy, but it could be. :) ). Maybe the Comparison pages <a href="http://drupal.org/node/266179">http://drupal.org/node/266179</a> could be integrated within that taxonomy too?</p> <p>Once we have a way for a module maintainer to provide the information above, here's my vision for how it would be used and displayed:<br> a) If you arrived at the Project page or any of the above resources on *.drupal.org sites (we have no control over the external resources, obviously), you would see a prominent block containing links to all of the module's other resources as listed above. These would be generated automatically on all of the above pages/sites.<br> b) People would be directed towards our wonderful nav hierarchy as the primary method for finding new contrib modules. There should also be a way to enter the module name or a keyword from the name and find the module (currently, even if you search for the exact module name using the Search box on drupal.org, it's not often the first hit, since the full text of nodes is being searched as well as the titles; contrast that to the search box on api.drupal.org, which works very well for finding functions if you know part of their names). This "taxonomy-based plus module name search box" navigation should apply to <a href="http://drupal.org/project/modules">http://drupal.org/project/modules</a>, <a href="http://drupal.org/handbook/config/contribmodules">http://drupal.org/handbook/config/contribmodules</a>, contribapi.drupal.org, modulehelp.drupal.org, the contrib module section of forums, and anywhere else people would go to find contrib modules.</p> <p>I realize that coordinating these blocks and taxonomy through *.drupal.org poses some technology issues, but I'm thinking Ideal Vision here, so I'd prefer to think about whether the idea makes sense first, before thinking about how to implement it or deciding it's impossible.</p> <p>Thoughts?</p>