When someone builds a Drupal site to solve a set of needs, many decisions are made along the way which shift the end product from off-the-shelf Drupal to a custom architected solution. While there is plenty of documentation for stock Drupal, and for many contrib modules, frequently there is no documentation for the specific customizations made to your site. Having no site architecture documentation is a problematical condition for any organization concerned about maintainability and ability to make changes to the site themselves.
If the site builder is a member of the organization that owns the site, then presumably you have some institutional knowledge regarding site construction. Has that site builder written anything down? If a third party builds the site, then it is possible you are given a very complex black box of a website with no actual documentation beyond a demo; which is less than you’d get when you buy a similarly complex package of functionality such as a small airplane or an industrial controller.
There may be good-sounding reasons for why this happened. A cursory search makes it seem like there is a lot of Drupal documentation out there (although it is probably not about your site’s unique features). Some developers may not think they are good at writing documentation, or not have any time for it in a tight schedule. Developers may tell you that because they followed Drupal coding standards, the site is self-documenting — all you need to do is look over the code. Regardless of the reasons, having no site documentation reduces maintainability and increases the cost to making changes to the site.
What are the implications of accepting the premise that all you need to do is look over the code or see a demo to understand your website?
-
Assumes every organization has at least one Drupal expert.
-
Wasted time for every team member to pore over the code. Your Drupal expert looks over the code. That only took 16 hours since there are actually 100,000 lines of code. Now another developer joins the project to add a new feature. That person has to spend another 16 hours to get up to speed? A Drupal themer is added a bit later. She has to spend another 16 hours to pore through the code? Then a contractor comes in to add a different new feature, and each member of their team has to spend 16 hours getting up to speed. Collectively that’s over 100 hours of time which has a measurable, non-trivial cost. Even if that first Drupal expert who pored over the code creates the documentation, there goes another block of hours. No matter what, a lot of hours had to be spent before anyone is productive on the new site. If you had just acquired a six-figure airplane that had custom features, would it seem right that these features were undocumented except to avionic engineers who can read the blueprints?
-
Code comments are not equal to sufficient documentation to understand the whole enchilada. There are likely key people in your organization who need to understand the architecture of the website without having to become Drupal experts. The premise that all you need is to read the code implies that only expert Drupal developers are capable of understanding the site architecture. I've seen it said about Drupal.org documentation that "Documentation is just as important as the code," and that seems right to me.
-
A demo is good, but mainly for the people who attended. It won’t help you as soon as you try to do something that they didn’t show. Also, as time goes by, fewer people will remember the details.
Goal/desired state:
For organizations concerned about maintainability, new Drupal sites would be delivered with documentation that explains how it is built, why it uses certain technologies, and the custom aspects of the site—i.e. those which differ from, or build on top of factory-standard Drupal. There should be enough documentation so that someone who never touched the project but knows some Drupal can understand how the site works without having to read every line of code.
Sizing the documentation effort
The amount of documentation should be proportionate to the scale of the effort. A large site needs more than a small program sub-site.
Documentation delivery
Around the time of site launch or shortly thereafter.
Questions which site documentation would provide answers to include:
Installation & Hosting
System dependencies
What custom/external libraries are used and why?
Any special requirements such as specific versions of PHP or other tools?
When new versions of custom libraries come out, how do we tell if they should they be upgraded?
How is the site built (drush make? custom script?)
— if Drush make process: document how to use, and how to update when a module is added
— Was a Drupal distribution used to build the site? which one?
— Installation profiles: are there any used? Why? What do they do? Are they essential or can that setup be done another way?
Hosting
Where is the site hosted? Where is the dashboard for managing hosting?
Administration & security
What site admin functions can only be performed by user 1?
What gets updated when cron runs?
What would get lost if you have to roll back to the most recent backup?
How do you control the site-offline message/screen appearance?
Security
What would not work if SSL were the default protocol?
Users
What are the different user roles and their use case?
How do prospective commenters or forum members register for a new account?
What is the site policy for retaining content/account info when cancelling a user account?
Can users edit their own profile info?
Structure
Content types
List of content types and their fields? Are there shared fields? What is the purpose of each content type?
Description of how the content types are used on the site?
Are there custom tables created in the database ? What for?
Description of how taxonomies are used on the site? Which are fixed vs. free-tagged?
Can content providers or admins tag content? Visitors?
Is promote-to-frontpage used on the site or not?
Is sticky-on-homepage used on the site or not?
Are there other, custom flags like promote-to-frontpage?
What is the purpose of each custom module?
What custom view modes exist for each content type? What are they used for?
Blocks/Boxes/Beans
What regions are available for blocks to go in?
What approach is used for layout of blocks and why?
How do you add/edit/remove blocks to the site?
What are the block types available to add?
How do you view a list of all instances of orphan blocks?
Is there a way to display a list of all non-orphan block instances (blocks in use on the site)?
Are there block/region combinations that are not possible/styled to use?
Views
Are Views used on the site? Where and why?
Exporting content
What RSS feeds are available? How do you add more or change something about the existing ones?
Site building
What modules are used, and what part each contrib module plays in meeting the requirements?
Are all contrib modules stock (i.e. were any patched)?
Are there sets of modules which need to be upgraded in lockstep?
What do the custom modules do?
What is the purpose of all persistent variables used on the site which are not part of standard Drupal or contrib modules?
Development/Dev Ops
Can one view a list of all commits made to the site since its inception? How?
What is the deployment process used for bugfixes to production? Are major updates handled differently?
Development and Deployment
What developer tools are known to work/installed?
Upgrade process -- any special considerations when performing minor/dot upgrades of Drupal or contrib modules?
QA & Testing
What testing methodologies are used to verify that the site functions / meets requirements?
Are there any unit or functional test packages created for the site? Describe them
Media
What are the preset image sizes and transformations that uploaded images become available in? (image styles)
Which non-factory-standard imagecache presets are encoded in modules vs. admin menus?
Are factory presets used at all?
External content
How can you embed external content into the site (i.e. via IFRAME? other method?)
Site search
What site search technology is used?
How does the site index content for site search?
How do you add more stuff to the index? How do you exclude content?
How do you boost content in results?
Workflow
What is the content workflow for the site?
What are the workflow states that content can be in?
Which content types use workflow?
Web Metrics
How do you turn on file tracking for Google Analytics? Event tracking?
Comments
What limitations are there with respect to turning on visitor comments?
URL redirects
What site redirects are handled outside of Drupal? How? Which ones?
Are all Drupal-based redirects visible at http://www.oregonmetro.gov/admin/config/search/redirect?
Multilingual
How many languages does the site support?
How do you add another language to the site?
What are the standard Drupal language codes for the most common languages used by the site audience?
Theming, grids & mobile layout
If the site theme is a custom theme, what is it based on? is it a sub-theme?
If the admin theme is custom, what does it do beyond a Seven or Rubik type admin theme?
What CSS preprocessor is used and why?
Site style
If the site maintainers need to add CSS to the site, what are the recommended files to add to?
What is the color palette used on the site?
What is the site typography and how do you access the webfonts?
(these last couple could easily be covered in a site styleguide, if you have one)
What UI enhancement tools are being used? (i.e. Chosen/Select2) What is involved with upgrading them?
Content presentation and reformulation
What inline styles are available to style content with (within an RTE)?
Mobile
What responsive grid system is used and why?
What are the responsive breakpoints? How do you add new ones?
Pre-development documentation
All deliverables from the various phases of the project:
The website requirements & functional spec, if any
Wireframes
Audience profile
Information Architecture
Style guides
User task analysis
UML diagrams (class, sequence, communication, etc.)
Interface wireframe/design
Web application inventory
Technical architecture
The above might be all stored in a Basecamp-style project site. A dump of the project site would be OK.
User documentation
Videos or other docs for content providers, editors, etc.
Value of site architecture documentation
Like having a guidebook to any big investment that gets used heavily over a number of years, documentation that decodes the custom site building decisions is worth doing. If your site costs $500K, the time it takes to document it is likely a very small fraction of the total time and cost. While it is certainly possible for a Drupal archeologist to dig into a black box Drupal site and create documentation after the fact, the effort represents a deferred cost. And like looking at visitor data in Google Analytics, often the intent behind some line of code, some module, some preset, or some block is difficult to intuit. That is why the team that builds a Drupal site is perhaps best suited to answer these questions by writing site documentation.
It doesn’t have to be 14 binders full of printed documentation; it could be an electronic document or a wiki. If each of the above questions took an average of 1-2 paragraphs to write, the result would be about 20 pages. Some diagrams might be useful. For any website that is handed over to my organization's web team, these would be the most valuable 20 pages we have.
Are there existing standards that could be used for this purpose? I'm familiar with Doxygen but it seems to me that using it doesn't answer many of the questions above which I have had about my organization's website.