How much documentation should come with a newly-developed website?
May 12, 2006 7:51 AM Subscribe
How much documentation should my non-profit expect from our web developer at the conclusion of our new website project?
The non-profit organization I work for is getting ready to sign a contract with a web developer to produce an entirely new site. We're investing a lot of cash in the project, and getting a pretty advanced end-product.
We have used volunteers in the past and have wound up with little, or no, documentation to use once they are out of the picture, and want to avoid that with this new site. So far, the developer has proposed four hours of training and one page of documentation for two core element [CMS, architecture].
What is an appropriate amount of documentation be for us to ask for, and what should it include?
The non-profit organization I work for is getting ready to sign a contract with a web developer to produce an entirely new site. We're investing a lot of cash in the project, and getting a pretty advanced end-product.
We have used volunteers in the past and have wound up with little, or no, documentation to use once they are out of the picture, and want to avoid that with this new site. So far, the developer has proposed four hours of training and one page of documentation for two core element [CMS, architecture].
What is an appropriate amount of documentation be for us to ask for, and what should it include?
J-Dawg's list is great. I'd also add that there should be complete payment information with license numbers if any of the CMS parts are off-the-shelf software or the like, as well as hard copies (or at least downloaded HTML/PDF documents) of any relevant documentation for those programs, before they get updated to new versions and older docs vanish from teh internets.
We also kept information at our NP about what CMS packages the developer might have passed up and *why*. Saves effort down the line when whingey board members want to know why you spent X thousands of dollars when s/he knows of an awesome program that only costs X hundreds.
posted by bcwinters at 8:40 AM on May 12, 2006
We also kept information at our NP about what CMS packages the developer might have passed up and *why*. Saves effort down the line when whingey board members want to know why you spent X thousands of dollars when s/he knows of an awesome program that only costs X hundreds.
posted by bcwinters at 8:40 AM on May 12, 2006
I suspect j-dawg's may be the best you could hope for, rather than what you should expect.
Also - When you say "advanced end-product" I tend to think that you'll have a highly interactive site with extensive end-user resources. Forums, file libraries, user accounts, comprehensive search features, admin interfaces for customizing all files and content, newsletter emails, support applications, etc. That would be advanced but also extremely expensive.
And one page of documentation plus four hours of training won't begin to cover that. You'd need days of training and extensive (probably online) docs. So either you are getting seriously shorted on the docs, or the site isn't "advanced". I'm not being snobby here, just trying to set expectations. If what you have is just a great looking informational site, then one page of documentation could be plenty.
For an informational site the "documentation" is largely just some details that will help other knowledgeable folks maintain the site. That is, the documentation IMHO isn't suppose to teach you to edit files, add new pages, or upload content.
Communicating what you need is key here. Training and documentation is the shit job of web development, and it's not uncommon for folks to skimp on it. But if this is a major development company they probably have a standard set of well developed docs they'll provide.
posted by y6y6y6 at 9:39 AM on May 12, 2006
Also - When you say "advanced end-product" I tend to think that you'll have a highly interactive site with extensive end-user resources. Forums, file libraries, user accounts, comprehensive search features, admin interfaces for customizing all files and content, newsletter emails, support applications, etc. That would be advanced but also extremely expensive.
And one page of documentation plus four hours of training won't begin to cover that. You'd need days of training and extensive (probably online) docs. So either you are getting seriously shorted on the docs, or the site isn't "advanced". I'm not being snobby here, just trying to set expectations. If what you have is just a great looking informational site, then one page of documentation could be plenty.
For an informational site the "documentation" is largely just some details that will help other knowledgeable folks maintain the site. That is, the documentation IMHO isn't suppose to teach you to edit files, add new pages, or upload content.
Communicating what you need is key here. Training and documentation is the shit job of web development, and it's not uncommon for folks to skimp on it. But if this is a major development company they probably have a standard set of well developed docs they'll provide.
posted by y6y6y6 at 9:39 AM on May 12, 2006
If you can provide charitable tax receipts for in-kind donations (such as pro bono work), then ask if they'd be willing to come in every, say, six months for the next two years for a couple of hours to provide refresher training or whathaveyou.
posted by joannemerriam at 10:51 AM on May 12, 2006
posted by joannemerriam at 10:51 AM on May 12, 2006
Please tell me that you're not building a CMS from scratch.
Use an existing one, like Drupal or Joomla and you'll have an installed reference base, administration guides, and the like.
posted by unixrat at 11:20 AM on May 12, 2006
Use an existing one, like Drupal or Joomla and you'll have an installed reference base, administration guides, and the like.
posted by unixrat at 11:20 AM on May 12, 2006
For all the web development industry likes to pontificate about usability, it often surprises me how atrociously poor most web folk are at documentation. Usability includes all stakeholders, including the site owner. Documentation is a core part of that. Everything that the owner can't reasonably know that they need to know should be documented in some form. Documentation is not a bonus extra or an enhancement. [/rant]
Having got that off my chest, there might not be so much you can do about it after the event if documentation was not itemized in your contract deliverables. One page isn't going to hack it and you are guaranteed problems down the road if you don't get more. If the developer is reluctant to do more, you might consider getting someone from your organization to carefully record any training and kill a couple of birds with one stone, as it were. Developers turn over quickly, you can't expect them to still be around in a few months, so the more you get now, the better. Nevertheless, paying them some kind of modest maintenance retainer might be worth your while for the first months of operation, which is when any big undocumented issues might arrive. Again, have a system to always record any answers from them, so that knowledge isn't lost.
posted by normy at 11:38 AM on May 12, 2006
Having got that off my chest, there might not be so much you can do about it after the event if documentation was not itemized in your contract deliverables. One page isn't going to hack it and you are guaranteed problems down the road if you don't get more. If the developer is reluctant to do more, you might consider getting someone from your organization to carefully record any training and kill a couple of birds with one stone, as it were. Developers turn over quickly, you can't expect them to still be around in a few months, so the more you get now, the better. Nevertheless, paying them some kind of modest maintenance retainer might be worth your while for the first months of operation, which is when any big undocumented issues might arrive. Again, have a system to always record any answers from them, so that knowledge isn't lost.
posted by normy at 11:38 AM on May 12, 2006
it has been my experience that unless documentation is outlined in the contract you should expect none. i agree with normay that it should not be considered an extra but it is.
posted by phil at 11:43 AM on May 12, 2006
posted by phil at 11:43 AM on May 12, 2006
j-dawg's list is great. Though this was included by implication in that list, it should be explicit in the contract: all logins (FTP/SFTP/SCP) including hosting info (username, password, domain, and path) plus any other passwords necessary for fully controlling and using the site.
It's amazing by how many clients have no idea what their site's login credentials are, or where they can be found.
posted by nakedcodemonkey at 12:18 PM on May 12, 2006
It's amazing by how many clients have no idea what their site's login credentials are, or where they can be found.
posted by nakedcodemonkey at 12:18 PM on May 12, 2006
To answer the question: you should expect to get whatever you're willing to pay for.
it should not be considered an extra but it is
For anything beyond simple usage instructions like how to access the site consider:
Most customers would rather have another feature on their site than a nice pile of paper describing the features they already have. So that's what developers spend their alloted time on.
Developers don't talk about documentation up front because it looks like unecessary overhead, quote padding to most customers. It's a good way to make a quote look uncompetitive.
The documenting process itself can be counterproductive: think about it, how would you like to have to spend time every day documenting your work, do you think this would slow you down or inhibit you at all?
Very few customers are actually willing to pay developers the same hourly rate to document that they are to make websites. So developers don't do it. It's just plain economic sense.
Prospective customers can immediately see the online results of a developers work, they can't see and don't care about documentation - in most cases it's wasted time in terms of developers' own business development.
posted by scheptech at 12:23 PM on May 12, 2006
it should not be considered an extra but it is
For anything beyond simple usage instructions like how to access the site consider:
Most customers would rather have another feature on their site than a nice pile of paper describing the features they already have. So that's what developers spend their alloted time on.
Developers don't talk about documentation up front because it looks like unecessary overhead, quote padding to most customers. It's a good way to make a quote look uncompetitive.
The documenting process itself can be counterproductive: think about it, how would you like to have to spend time every day documenting your work, do you think this would slow you down or inhibit you at all?
Very few customers are actually willing to pay developers the same hourly rate to document that they are to make websites. So developers don't do it. It's just plain economic sense.
Prospective customers can immediately see the online results of a developers work, they can't see and don't care about documentation - in most cases it's wasted time in terms of developers' own business development.
posted by scheptech at 12:23 PM on May 12, 2006
Four hours training and a couple of pages of doco sounds worryingly small, but of course we don't know how big/complex the site is. If the site has two pages, two pages of documentation is probably enough!
posted by AmbroseChapel at 1:20 PM on May 12, 2006
posted by AmbroseChapel at 1:20 PM on May 12, 2006
Response by poster: thanks for all the input. the end product will be pretty complicated, so it's good to know that it's not outlandish to ask for complete backup and resources so that we can understand it, manipulate it, and prevent immediate obsolescence. [in case of a move by the programmer to bora bora]
our final contract meeting is tuesday, and this should give me a great outline to walk in with!
posted by rubberfish at 11:59 AM on May 13, 2006
our final contract meeting is tuesday, and this should give me a great outline to walk in with!
posted by rubberfish at 11:59 AM on May 13, 2006
I'm an information architect, not a programmer, but I do try to keep up with my own documentation, both because I think it's good manners and also so that I can go back to my own work and understand what's going on after any length of time (whether the project is in utero or already developed).
I started out as a copywriter (and now write for magazines for fun), so I take a less technical approach.
For a corporate e-newsletter I needed to hand off, I started by discussing how the files are set up and where to file and find assets. When I got into the guts of how to set up the newsletter ("first do A; next go here and do B...") I found it was helpful to insert comments that stated "At this point, you may want to do X -- but don't worry -- you'll get to that later, when you set up the Z"...
These "head them off at the pass" statements allow users to feel like their instincts aren't crazy, and lets them know that you've worked through the steps in a logical order.
Of course, hopefully you *have* worked through things in a logical order....
posted by mdiskin at 10:21 AM on May 14, 2006
I started out as a copywriter (and now write for magazines for fun), so I take a less technical approach.
For a corporate e-newsletter I needed to hand off, I started by discussing how the files are set up and where to file and find assets. When I got into the guts of how to set up the newsletter ("first do A; next go here and do B...") I found it was helpful to insert comments that stated "At this point, you may want to do X -- but don't worry -- you'll get to that later, when you set up the Z"...
These "head them off at the pass" statements allow users to feel like their instincts aren't crazy, and lets them know that you've worked through the steps in a logical order.
Of course, hopefully you *have* worked through things in a logical order....
posted by mdiskin at 10:21 AM on May 14, 2006
This thread is closed to new comments.
* Thorough documentation about how the system was built, and using which tools.
* Information about how to use the CMS and edit other assets.
* Information about dealing with the ISP and web hosting space (assuming you haven't dealt with all that internally)
Plus, he/she should commit to doing two other things:
* Provide you with a CD containing a complete copy of the site, all original assets with layers preserved (e.g. PSD and AI files), and backup copies of all his paper-based documentation, including training notes.
* Comment the site code so that if you need a revamp in a year and he/she has moved to Burkina Faso, another developer can pick up the project with a minimum of detective work.
And yes, you should get committments for all this in writing.
Best of luck...
posted by j-dawg at 8:25 AM on May 12, 2006