Wow, cool! Thanks for the positive responses! Ok, I created a group for this proposed module here: http://groups.drupal.org/site-documentation-module Feel free to post there with comments, ideas, etc. -Angie On 13-Apr-07, at 9:54 PM, Angela Byron wrote:
When inheriting a site from a client and trying to figure it out, there are a number of things one normally does...
- Go to the content types listing and take a look at what types exist, and what the field definitions are for those types. - Check out what roles there are, and what permissions are assigned to those roles. - Check out what taxonomy vocabularies exist, and to which content types they're assigned - etc.
This is all rather time-consuming, as it requires going to about 50 admin screens, and it's difficult to get a "big picture" of what's happening.
Having been asked to write a document containing some of these things on a site, I'm thinking of writing a module that basically nicely formats a db dump into an HTML page so you can get a bird's eye view of what the site entails. Example output might be:
---
<h1>Site documentation for Example.com</h1>
<h2>Goals</h2> [insert site goals here; why does the site exist? who's its target market?]
<h2>Overview of architecture</h2> [insert overview of architecture here; how various pieces fit together and why]
<h2>Enabled module list</h2>
<ul> <li><strong>Custom module</strong>: A custom module for the site. Description taken from .info file.</li> <li><strong>Logintoboggan</strong>: Improves Drupal's login system.</li> <li><strong>Pathauto</strong>: Provides a mechanism for modules to automatically generate aliases for the content they manage.</li> </ul>
<h2>Content types</h2>
<h3>Page</h3> A static page, like a contact page or an about page.
<h4>Fields</h4> Title Section (Vocabulary) Body
<h3>Announcement</h3> A news announcement on the site.
<h4>Fields</h4> Title Category (Vocabulary) Description (Body) Attribution (Text)
<h2>Roles</h2>
<ul> <li><strong>anonymous user</strong>: [insert description here]</li> <li><strong>authenticated user</strong>: [insert description here]</ li> <li><strong>administrator</strong>: [insert description here]</li> </ul>
---
Perhaps this would include an intermediary step (a form) would let you enter in broad descriptions for the site, plus descriptions for roles, etc. Because this info could be just about anything, it could be stored maybe as a serialized array somewhere?
It could also have the option to export a blank template which you could fill in manually when you spec out a new client site.
I was thinking also of a settings page where you can turn on/off the sections you wish to be included. And it would have to implement a hook so other modules could expose their things to being included in the documentation output.
What do you think? Crazy idea? Stupid idea? Anyone interested in helping to spec something like this out?
-Angie