This is undoubtedly a great idea, and would fit in nicely with what many are no doubt planning as project wiki/tracking documentation sites that would not only help analyze an existing site, but also analyze, design, implement and test a new one.
In this sense, there would need to be a structured relationship between the architecture, on the one hand, and what you are including as objectives of the site: how would all of this relate to the prospective users (list users, user roles, which may or may not coincide with the drupal roles) and the intricate pathways through the site that would make up the user stories, partially captured, at a minimum, in a "site-map" of the site. (a tree built around all the possible menus/menu routes, per drupal role).
If that doesn't sound too confusing (sorry, it's what's in my head a lot these days) it is meant as a contribution and possible enrichment to what you are proposing.
On 4/13/07, Angela Byron <drupal-devel@webchick.net> 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