[development] Idea: Site documenter module

[Victor Kane]

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 at 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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.drupal.org/pipermail/development/attachments/20070413/39c5a3ae/attachment.htm