[development] Idea: Site documenter module

[Rob Barreca]

> 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.
Yeah, this is good stuff, especially in the realm of installation 
profiles like Aaron said to get an idea of what should be included at 
install time.

Rob Roy Barreca
Founder and COO
Electronic Insight Corporation
http://www.electronicinsight.com
rob at electronicinsight.com



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
>