I dreamt last night that I was part of an Arts program in a obscure North Eastern College. As a week long program, the schedule was packed with events, classes and to dos. We were all excited to be there - inspired to create, explore our selves.
Throughout the week, there were distinct daily conversations; some students were engaged in the similar conversations; other students were lost at what was going on. The engaged were busily creating and producing; the disenfranchised were wandering and floundering.
On the final day as we prepared our portfolios, some students were actively captivated. Their efforts, a vector, moving toward a final destination. Most of the other students seemed frantic, meandering in indecision.
At orientation, we received a flimsy conference bag containing a beige paper back with writing on the cover, lacking a table of contents and no title pages, whatsoever. Seeing this as being worthless, most of the students (including myself) saw it in our welcome bag and never looked at it again. I mean, it was beige after all.
Around two o’clock on the final day with my portfolio due in several hours, I looked at the title-less book and read the cover. While as vague prose, it seemed to indicate that we should commit all our work to the repository every so often with tags that indicate states. The pages of the book were numbered in chunks from 0 to 7. We should read 0 on this day followed by the consecutive. As I flipped through those arrayed pages, I saw random questions that evoked conversations I heard throughout the week. The title-less books contained no direction and no closure.
In a moment of clarity, I realized that this was a trick from the Art Department; to separate those who were innately curious, who explored their environment, who just “got” it - from those who don’t. Feeling the fool, I thought, “Well, at least I committed all my work” and went about amending tags to my previous commits (I mean, this is a dream so of course we are using GIT!), assembling my work to reference the conversations and pulling it together before the final push.
Other than being a typical dream, this is a great parable about most of the web development projects I have had the, um, pleasure to work on throughout my career. Also, it is a lesson in the importance of exhaustive documentation.
I use the term “exhaustive” because I want to point out the breadth and effort that should go into project docs. Well commented code is good … no it is great; but unfortunately, not enough.
Pre Pro Post
In the arts, we learn that 3 is a sacred number. You can build a whole career on “three chords and the truth” - just ask Lou Reed. Our visual field, demarcated by the rule of thirds, can reveal an aesthetic composition. In development - there are somewhat similar notions. In Project Management, there is pre-production, production and post-production.
When I think “Exhaustive” - I think of post-production; creating documentation after the project with a single group in mind:
The People Who Will Inherit the Website.
No, not the team that you worked with to build the site. Not them, you silly fool. The people who come after. The admins who will work on the site - after you trained the initial ones. The developer who inherits your site when you move on to the next one. You when you come back to the site after not looking at it for 18 months. The third party content editor who has been hired to write a blog post on the site.
The type of documentation that you need to write can be summed up in three categories:
- Administration
- Content Editing
- Development
Exhaustive Admin Docs should detail:
- Permissions and roles overview
- The Menu System
- User management
- Page management
- Block Management
- Backup Policies (and Restore Policies)
- Important Names and Contact Information
Exhaustive Content Editing Docs should detail:
- Introduction to Database CMS
- Content addition, pruning and un-publishing (you know you never delete content, right?)
- Content Surfacing (Views)
- How the landing pages work (Panels, Views, etc)
- How to create a menu item (or unpublish one)
- How paths are determined
- What is a Taxonomy and how to use it
- Detail project workflows
Exhaustive Development Docs should detail in easy to ready summary pages:
- All admin/dev usernames, passwords
- FTP usernames, passwords
- SSH usernames, passwords
- Hosting / DNS servers with contact information (note esp helpful/knowledgeable staff)
- Detailed workflow of the site structures fromt both a Front End and Back End perspective
- Overview of custom modules (as the modules are commented well)
- Abstracts of exceptions why something works not in the way you would think it would work
- Abstracts of major obstacles and SNAFUS
- To Do List
All of this information should reside in a password protected area. I would look to keep this information on the actual site rather than in a third party wiki. NancyDru has a great module http://drupal.org/project/sitenotes whose purpose is just this.
When I was at Sony Music, I created a documentation site that detailed all the above as well as snippets. While there I wrote http://drupal.org/project/hyperspace to create “dynamic documentation” -> where admin paths would turn into the links one of the many the sites that you were working on.
In Summary
Clear, easy to parse, detailed documentation should be a necessary component in our industry. Like scheduled backups, they seem extraneous until you need them; then they are invaluable. Add the time it to author them in your initial estimate and future admins, content editors and maintainers will remember you fondly.
And please, stay away from beige.