Documentation Process
The more I develop web applications, or even XHTML/CSS templates, the more I realize the need for project documentation. The problem is, I haven’t found an easy or efficient way to provide this documentation to the client. So this post is more of a question on which I intend to write a follow-up article.
How do you document your deliverables? What processes do you use? What formats to you provide? I’m interested to hear what the general community thinks about the need for documentation.
Clarification: I would like to set the focus on the documentation of the deliverables, aka the help documents. The ‘manuals’ if you will. What level of depth do your projects help documents require, and would you find a more automated, online version of help documentation useful?
Post and Author Info.
Published April 11, 2005 by:
Commenting is currently off for this post.
So far there are 4 comments.
Well, this all depends on who you are, who you are working for and the request at hand. Anyone who has done design or development on a professional level will tell you at least 5 stages:
Now in the past there has been times where I have done freelance work that I pretty much forgo two of those steps (two that professionals argue to be the most important). But, within that deployment phase, usually comes a presentation to your employer, along with all documentation of the project.
Now I work as an ASP Web Developer (odd, as ASP is the slow learning child of all languages on the web), and I work for the same client each project. No real documentation is required when that person can say “Ryan, you got a minute…” and have me go over something with them.
However, in other instances I have provided documentation that actually received some praise. I am terrible at documenting, I look at the final product, and see what I made…I know how to use it because I made it. But I do have a few tricks on how to write better documentation.
The first being; let others in your field play with. If an educated user finds themselves wondering about something; a novice is likely to experience the same question. This would be good for co-workers, when you are done, let them take a look at your finished project; jot down any questions or comments they have, then go back and write on them a little bit more in-depth than you might have.
Give it to a friend or a family member to play with. I typically ask my sister, my girlfriend, and my best friend to sit down and take a look at something I’ve created. They are all “everyday surfers,” with limited knowledge; and when providing to a client, unless known otherwise you should always document it as if they are the “everyday user.”
You want to provide adequate notation on how everything works, and in a lot of cases why it works that way. Telling them why it works that way can be the hardest thing to do, so you just have to pay attention how you word it. And always try to give a demonstration when deploying it; it saves you a lot of “Ryan (in your case, Steve)...the website is broken.”
April 11th, 2005
Ryan: Very thourough. I don’t think I’ve ever had a comment before that was over 4 times longer than my post… :) I agree with your assessment of the levels of documentation, so to more simplify this question, I think I’d like to limit our scope to the deliverable documentation, aka the help documentation.
April 12th, 2005
Our company has a document with checklists and holds necessary information about the client and their needs.
For each client we print up a new doc (about 6 pages) and go through each one, one at a time.
We also have documents that overview the company philosophy just “what we do,” but that’s all part of the general job duties and description that each developer, designer, and programmer is held accountable for knowing all the time.
The use of Standards for developers, accessibility and usability for the site testers, the use of OOP for programmers, appealing and meaningful graphics for the designers. etc.
The steps to developing a website go like this.
If I could turn this into a drawing, I would pull out “Usability Testing” and “Communication” out and have them sit on the side pointing at the entire program; meaning that those two should be going on through each step along the way.
April 12th, 2005
It depends on the scale of the project, and the requirements of the client how much detail we go into with our documents. For example, today I just finished writing a 125 page business rules document for a web application that we’re releasing into the clients hands tomorrow. For the most of our projects though, there is just a simple 10 page or so help document, manual if you will, that accompanies the final product.
April 14th, 2005