[development] Idea: Site documenter module

[Matthew Farina]

This is a great idea.  This would not only help someone who is  
picking up a site they didn't design but help people think through  
their own designs a little more.

- Matt

On Apr 13, 2007, 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
>