Idea: Site documenter module
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
Angie, having been in similar situations a number of times, I think it's a fantastic idea. Count me in for helping to spec it out, and to code if need be. Perhaps a Drupal group is in order? William 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...
great idea! this could in turn be extended to create installation profiles as well. aaron 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
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@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
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
<h1>Site documentation for Example.com <http://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]
I have been thinking about a related module that might make sense to fold into yours. ideally mine would be in core one day. the idea is to tell the story of a site's construction. i call this fictional module 'credits' or 'colophon'. and admin enables this and a page shows up at a known path like /credits. there, the admin can fill in some summary info about the site and the designers, developers, clients, etc. who work on the site. the role of each might optionally be detailed. in addition i would add a more drupal specific section where admin can optionally disclose what modules/themes are in use and can make comments about innovative use of each. i would even have this module expose a microformat so that this data could be aggregated and presented somewhere, one day. i did a bit of research and didn't see any prior art for web site credits microformat. sorry for hijacking this thread a bit.
On 4/13/07, Moshe Weitzman <weitzman@tejasa.com> wrote:
<h1>Site documentation for Example.com <http://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]
I have been thinking about a related module that might make sense to fold into yours. ideally mine would be in core one day. the idea is to tell the story of a site's construction.
i call this fictional module 'credits' or 'colophon'. and admin enables this and a page shows up at a known path like /credits. there, the admin can fill in some summary info about the site and the designers, developers, clients, etc. who work on the site. the role of each might optionally be detailed.
in addition i would add a more drupal specific section where admin can optionally disclose what modules/themes are in use and can make comments about innovative use of each.
i would even have this module expose a microformat so that this data could be aggregated and presented somewhere, one day. i did a bit of research and didn't see any prior art for web site credits microformat.
sorry for hijacking this thread a bit.
Colophon is the common name for such pages on many sites. The feature module used on Drupal.org can be a base for what you want. It has "categories" that show up as heading (could be designers, developers, ...etc.) and under it there are descriptions. A few checkboxes can be added to say "show Drupal version number", and "show enabled modules". -- 2bits.com http://2bits.com Drupal development, customization and consulting.
I suggested the equivalent of a phpinfo() page at last Sacramento Drupal user meetup and it did not go over well. You'd have thought I suggested using a common admin password for all Drupal sites instead of just allowing a site admin the OPTION of showing other people what modules a site is using. Someone there (sepeck?) said that enabling the the Drupal module reports the module sites are running back to a central server... "Drupal - Lets you register your site with a central server and improve ranking of Drupal projects by posting information on your installed modules and themes" So someone has the module information for a number of sites, but I've never seen it. I don't really buy the "making it easier for hackers" argument against sharing this information. Anyone who checks their logs knows how often bots are scanning their servers for known, exploitable scripts. Creating a standard sitemap-like (http://www.sitemaps.org/) format/location for other developers to see what's being used and who's doing it would be a big benefit to the community and IMHO wouldn't be giving the "bad" guys information that could get another way. The request to know what modules are popular is a fairly common one from people new to Drupal. The response at SacDUG seemed to be that developers should monitor the issue queue for several months before installing any module. That's not really realistic advice for most people looking at Drupal as a framework for their site. I don't have the ability to share the information collected by the Drupal module, but I'd be willing to install a module like this on my sites. - Kevin Reynen On 4/14/07, Khalid Baheyeldin <kb@2bits.com> wrote:
On 4/13/07, Moshe Weitzman <weitzman@tejasa.com> wrote:
<h1>Site documentation for Example.com <http://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]
I have been thinking about a related module that might make sense to fold into yours. ideally mine would be in core one day. the idea is to tell the story of a site's construction.
i call this fictional module 'credits' or 'colophon'. and admin enables this and a page shows up at a known path like /credits. there, the admin can fill in some summary info about the site and the designers, developers, clients, etc. who work on the site. the role of each might optionally be detailed.
in addition i would add a more drupal specific section where admin can optionally disclose what modules/themes are in use and can make comments about innovative use of each.
i would even have this module expose a microformat so that this data could be aggregated and presented somewhere, one day. i did a bit of research and didn't see any prior art for web site credits microformat.
sorry for hijacking this thread a bit.
Colophon is the common name for such pages on many sites.
The feature module used on Drupal.org can be a base for what you want.
It has "categories" that show up as heading (could be designers, developers, ...etc.) and under it there are descriptions.
A few checkboxes can be added to say "show Drupal version number", and "show enabled modules". -- 2bits.com http://2bits.com Drupal development, customization and consulting.
On Apr 15, 2007, at 1:34 PM, Kevin Reynen wrote:
So someone has the module information for a number of sites, but I've never seen it.
right. unfortunately, the project.module side of things was never worked on to display this usage info in any way. furthermore, since so few sites would want to enable the drupal.module (because of the (basically insecure) distributed authentication functionality), the usage statistics it generates are close to meaningless, anyway. luckily, help is on the way. now that the update_status.module is in wide-spread usage for 5.x, and slated to move into core for 6.x, *lots* of sites are now (or will be soon) using this module to find out if their sites are up to date. we're going to be adding functionality for sites to optionally let drupal.org store these queries (module and version info) so we can get much more meaningful usage stats. furthermore, drewish will be spending all summer working on this sort of thing for his google summer of code effort on project quality metrics. we'll be making this data (anonymous summaries of it, of course) available for people to see on project nodes, as a new method to sort modules for downloads ("browse by usage" or something), etc, etc. links for interested readers and folks who want to help: http://groups.drupal.org/node/3314 (drewish's SoC proposal) http://drupal.org/node/128827 (issue about collecting the stats) http://drupal.org/node/136172 (issue about the XML-RPC protocol for these update queries) http://drupal.org/node/52475 (issue about browse-by-popularity) cheers, -derek (dww)
On 15-Apr-07, at 4:34 PM, Kevin Reynen wrote:
I suggested the equivalent of a phpinfo() page at last Sacramento Drupal user meetup and it did not go over well. You'd have thought I suggested using a common admin password for all Drupal sites instead of just allowing a site admin the OPTION of showing other people what modules a site is using.
Well, the simple solution to this is just permission: 'view site documentation' .. you can enable it only for your admin role, or for anonymous users if you're into that... Anyway, I've started a thread at the Site Documentation module group to brainstorm ideas on what to actually document... it's a lonely place atm, so if you want to help stop by http://groups.drupal.org/ site-documentation-module -Angie
Interesting and useful idea, Moshe. I'm not quite seeing why it would be a core module, though. Interested in hearing why.
Chris Johnson wrote:
Interesting and useful idea, Moshe. I'm not quite seeing why it would be a core module, though. Interested in hearing why.
a big part of this proposed module is about teaching others how to build a site like yours. if knowledge sharing is a core part of drupal, then this module is a candidate for core. we shouldn't really debate this point much, since !module_exists().
Thanks for the reply, Moshe. I didn't mean to start a debate; just wanted to know the reasoning.
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
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
Hi,
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.
This is a great idea. Apart from anything else, as I'm still a beginner I could view such a page and treat it as a kind of checklist: "this is what an advanced Drupaller would need to know at a glance to understand the site; these areas are therefore what I need to tie down before my site can get under way." Would it also be useful (for e.g. complex themes) to be able to get some sort of JavaDoc-like self-documentation out of the templates, as then what you're proposing covers the likeliest locations of both custom data- and codebase? phpDocumentor would cope well with the functions in template.php but I don't know how much use it is for documenting combined HTML/PHP files. Regardless of what gets decided I'm offering a hand. However, I'm still at the level of expertise where I could be as much a hindrance as a help, so I don't mind if I get put on grunt work/testing. Cheers, J-P
participants (12)
-
Aaron Winborn -
Angela Byron -
Chris Johnson -
Derek Wright -
J-P Stacey -
Kevin Reynen -
Khalid Baheyeldin -
Matthew Farina -
Moshe Weitzman -
Rob Barreca -
Victor Kane -
William Smith