how to prepare webproject Documentation

The Project Life Cycle

While doing the research for this article, I pulled out the Encyclopedia of Computer Science, editors Anthony Ralston and Chester L. Meek, Petrocelli/Charter, 1976. It is definitely a first edition classic, but some things are timeless. It states in the Documentation listing:
"Documentation is a vital part of developing and using a computer-based system. In some commercial organizations, 20 to 40% of the total development effort goes into the documentation of the new system, recording how the new system is to work and how it was developed." Author, K.R. London
I was curious if that was still true today, and if so, why documentation is not given the media coverage it deserves. I could not find a lot of information on the costs of documentation during the Project Life Cycle. (See Figure A.) I suspect that these costs are often understated or not properly collected. For IT professionals whose job is to develop working systems, many may consider admitting the actual costs of documentation as embarrassing or reflecting poorly on their productivity and work. Your opinion of the documentation phase of the Project Life Cycle likely depends on your role in the IT organization. If you are a manager or project lead, documentation is critical to the success of the project. If you are in a non-managerial position, documentation is an annoying nuisance that gets in the way of your real work. While the 10 tips below are mainly targeted toward the latter category, managers and supervisors can also benefit from them.

Figure A

Source for the seven Project Life Cycle steps: WikipediA

#1: Document with pictures if possible

The old adage a picture is worth a thousand words means that by using pictures to augment your text, you can minimize the length and complexity of your documentation. System users like having pictures, diagrams, tables, and bulleted lists for quick reference.

#2: Give examples

Examples are an excellent way for end users to quickly grasp concepts that they may not fully understand. It is also a good way for an end user learning new software to sit down and tackle a new challenge more easily. Here is an example of documentation with pictures:

Previous Versions in Vista Business, Ultimate, and Enterprise

Previous Versions is the term that Microsoft uses for saving shadow copies of a file. If you are working on a document or any other project that is labor intensive and have accidentally lost part or all of your work, you can go back to a previous version. Think of it as an automated way to make snapshots of how the file looked at previous points in time.
But first you will have to configure Vista so that Previous Versions (Figures B through E) will be turned on for the logical drives/partitions that you want the ability to restore the previous versions of your files.

Enabling Previous Versions

Figure B

Select Start | Control Panel

Figure C

Left click Advanced system settings — Left click Continue if prompted by the UAC (User Account Control)

Figure D

Left-click on the System Protection tab

NOTE: The Vista logical drive/partition is already enabled by default. Change this setting only if you fully understand the consequences of doing so.

Figure E

Scroll down and check logical drive

Left-click on the scroll bar and scroll down through the logical drives/partitions until you find the one for which you want to enable Previous Versions. That logical drive name is Documents in this example. Left-click the check box next to the logical drive name.
NOTE: Shadow copies are created based on the time and frequency of system created restore points. According to the Vista help file, this is typically once a day.
Left-click Apply and then left-click OK to close the System Properties window. Left-click File | Close or left-click on the red X box in the upper-right part of the Control Panel | System window to close it.
To restore the previous version of a file, you can right-click on the filename in Explorer and left-click Restore previous versions.
NOTE: Once a shadow copy of a file has been restored, it is no longer available for a second restore. Another shadow copy will not be created until the next system restore point is created. This means that any files saved before the next system restore point cannot be restored to the same previous version you used previously. Caution should be exercised saving files after using the Restore Previous Versions option until the next restore point occurs and another shadow copy can be created.

#3: Don't presume to assume

Even if you know your targeted user base, your documentation needs to be written so that anyone with only basic computer skills can read it and learn how to properly use the system. Step-by-step instructions should be provided when possible, but consider placing them in an appendix, a separate chapter, or making them available via a hyperlink to avoid clutter. If you are doing the documentation, change your mindset so that you place yourself in the shoes of a new system user. That can be difficult to do at first, but if you pay attention to details and fully document all features and functions, you can create documentation that doesn't assume that the user can figure out information and procedures you have failed to include.
Don't assume that your end user understands all of those acronyms that litter the IT landscape. The first time you present a new acronym, detail what the acronym stands for.

#4: Anticipate problems

When testing your system, you should have tried your best to break the software any way you could. If your software has known issues (developers like to call them issues; end users call them bugs), document a workaround and provide it to your users and the help desk. You will not only save a lot of frustration for the end users but also a lot of extra calls to the help desk.
Document the events that are inevitable during the lifetime of any long-lived system:

• What workarounds are available while the system or network is down?
• How do you recover from a server outage, a hard disk crash, or database corruption?
• How does someone who knows absolutely nothing about your system get the system up and running again?

Your documentation should anticipate these problems and provide a detailed plan and instructions for system recovery.
Will the person who replaces you know where to find your documentation and any purchased vendor application documentation? All of these documents should be neatly organized and stored together in a safe and known place.
Another good example of anticipating problems is the Y2K Millennium Bug problem and solution. The media began reporting in the late 1990s that systems and software were likely to fail due to the storage of only two digits for the year in legacy systems. This problem was anticipated in advance and a lot of effort went into fixing the problem before it occurred. Software in development was built and certified as Y2K compliant years in advance of January 1, 2000. The results were remarkably successful. Except for a few minor reported problems, New Year's Day 2000 was a festive occasion and not a disaster for the IT community, though a lot of us were on-call just in case.
The same mindset can be used to anticipate problems that might arise in your documentation. The Y2K problem also illustrates the need for continual document updating. System/Internal Documentation was changed to note the Y2K compliance or noncompliance of software and systems. For older legacy systems, workarounds were found and documented.

#5: Test your documentation

Sit down and follow your own instructions. If you are documenting the building of a server, a network, or any other IT system, start with a clean partition and build everything from scratch. You will undoubtedly discover that you have left something out or that some of your instructions are unclear.
Work with an uninformed but committed co-worker to get feedback before you publish. Let them test out your documentation.
You will be amazed at what you will learn when you sit a person down to work with your software and documentation for the first time. A lot of features of the software that are obvious to you will not be so obvious to someone who is honest and willing to work with you. Watch closely what your guinea pig does while navigating your software. Ask for feedback and take notes.
I remember the feedback I got during the testing of one of my projects. The feedback was written in an e-mail so I could review it point by point. The first thought that came to mind was "how long will this take to do?" You may also take these comments as critical or personal. Don't make that mistake. Looking back on it now, I should have implemented more of the missing features that my helpful critic had provided.
Use this opportunity to make final tweaks to your project. Feedback during the documentation process can help you make the overall project more successful.
I was writing a review for the Foxconn 975X7AB-8EKRS2H motherboard and I ran across two errors in the manual. I wasn't the first person to review the board. Foxconn had missed the errors and all of the other reviewers had missed the errors as well. One mistake in the manual was far from trivial.
The diagram in the manual showing the normal position of the clear CMOS jumper setting was incorrect. I know because when turning the motherboard over to verify the proper seating of the heatsink, the jumper fell off. I put the jumper back on according to the instructions in the manual. The computer failed to POST. After a careful look at the tiny diagram on the motherboard, I discovered the error and corrected the misplaced jumper.
I was working with a tech from Foxconn at the time who was kind enough to answer my questions and I informed him of the error. Documentation errors like this are easy to miss and can lead to potentially large costs to the manufacturer. I would have missed the error myself were it not for the fact that the jumper had been loose enough to fall off when turning the motherboard over.

#6: Humanize your work

How many times have you read a user manual and wondered if there really was a human at the other end of the creation of the manual — or was it a computer that made that manual? Although you don't want to create a colorful novel, humanize the document just enough with some of your personality so that a reader will feel a little more comfortable while reading it.

#7: Explore new technologies

Documentation can be costly even when done correctly. New technologies will continue to be created to help create more effective documentation that is less costly to develop. Look at these new tools as opportunities to reduce the time and cost of the documentation process.
Documenting as part of a project team can be especially difficult. Your documentation needs to be shared and added to the documentation of other team members. Changes have to be made, often on a daily basis. Software exists that will allow for this and will not only help to ensure a standardized end product but will also help to foster the sharing of ideas and knowledge among the team members.
While working at CSC (Computer Sciences Corporation) I had experimented with Microsoft's Agent and text-to-speech technology with mixed results. I always thought that it offered some wonderful ways to guide a new user through some of the features of my system. Some may remember that offensive little paper clip character with the blinking eyes in Word 97. It was slightly more than annoying.
With Agent, you can have your character move across the screen, point to a drop-down box, programmatically open the drop-down box, and allow the character to speak to you about the options presented. I created a guided tour of my software and let Peedy, the parrot, point to boxes, fill in text boxes, change screens, and generally walk the end user through the entire process of creating a new record in the database.
I found that using Agent saved me from having to write many tedious pages of documentation that detailed the steps necessary to create, save, and modify new records. It was also fun to develop. It allowed my creative side to participate in a positive and beneficial way. Creativity is pre-programmed in most developers and is a key component of what makes them successful. Creativity can and should be considered when developing your documentation, depending on the standards and expectations of your company.
The only feedback I received about my MS Agent experiment was that someone had too much time on their hands and it was never taken seriously, at least in part because of the comical looking character. It wasn't a lot of extra work to build, but it did require me to learn some new coding techniques. It was a pleasure when a person in our department was to be trained. I told them to take the guided tour. Perhaps Microsoft was ahead of its time, and with a more respectable character, this type of technology could still become mainstream one day.
I recently built a computer for my dad as a 50th wedding anniversary gift. I documented some notes marked Important PC Notes PLEASE Read and left a shortcut on the desktop. I also created an audio file that documented the features and use of the computer. I had to ask him if he looked at my notes, but he offered to tell me that he took the case and computer audio tour.
These are just a few examples of alternative ways to document. It is this humble writer's opinion that new ways to document are underutilized and underestimated for their simplicity and potential impact in today's corporate environment.
The elusive be all and end all documentation software package has yet to be developed, but there are a number of useful documentation tools that are designed for specific documentation tasks.

#8: Do the documentation yourself if possible

The best person to document is the builder. After all, who knows the system better than the system builder?
If you are the system builder, you are likely a crack programmer. But just mention the word document to a programmer and you will be given that "you've got to be kidding" look. If forced, programmers will document their work, or at least make an attempt to create something that will pass as documentation. I know. I have seen it all too often and even been guilty of it myself.
And that is a real shame because a programmer with good documentation skills is a valuable asset to the company. What will your manager remember at performance review time if another person had to do the documentation for your project? My guess is it won't be that you deserve a promotion, raise, or bonus.
While not exactly fun, documentation can be rewarding when done correctly. Not only will you have a better overall project to present to your customer, you will also greatly reduce the future support time you will have to provide. You can also reduce the amount of support and maintenance time for the help desk.
When working at CSC, I was given the opportunity to be the project lead for the design and creation of our global reporting system and infrastructure. I got to see first hand the other side of documentation. We had a very good programmer in the group who was doing Crystal Reports API work and custom function building. It was obvious to me that his knowledge was unique to him and needed to be shared with the rest of the team, and what better way to do that than to properly document his work? I wasn't entirely successful in getting him to explain his work to the point that another person could step in and pick it up. He did list and explain the function names, how to use them, how they worked, and what they accomplished, and that was very helpful to the other members of the team.
There seems to be an unwritten rule in the Realm of the Code that programming skills are inversely proportional to the amount of documentation programmers have to do.
The second greatest compliment ever paid to me in my career was when I had to give a presentation to our global technical support team. I had to create and present documentation on how to build a reporting server. One of our database administrators was a chap from England who had to sit in on the presentation. He looked at the How to Build a Reporting Sever document and, to paraphrase, commented how good the documentation was and that he should be able to build a reporting server using my documentation. Statements like that make all of the hard work worth it. And it wasn't a compliment for the main project work — it was for the documentation.

#9: Coordinate the development of the End User Documentation with the Internal/System Documentation

You can cut your documentation time if you build your User Documentation at the same time you write the System Documentation. You can share some of the information between the two and reduce missing information. Even if you don't want to or it is inappropriate to share information between the documents, you can benefit from topics in one document that will prompt you to include additional documentation in the other.

#10: Follow department or corporate documentation guidelines

Create and follow standard formats and guidelines. This will help to ensure that important information is not excluded and allow for easier reading by system users.
The one time I had a dedicated documentation expert work with me to document my system was at Hughes Aircraft Company. The results were excellent. The format was the department standard and the results were better than I would have done. It required a lot of time and effort to get those results. The documentation expert needed access to my beta system and access to me so that I could answer questions. This is more expensive and not all companies have the resources to allocate to professional documentation, but the results can be excellent if the system builder can verify that important information is not misinterpreted or left out of the end product.
I was very fortunate that I had a former engineer who was also excellent at writing documentation. He understood what the system was designed and built to do and he filled in the blanks by actually using the system and discovering for himself how it worked. You may not be so fortunate.
In this day and age of global marketing, sales, and support, documentation should also follow country or regional standards. I am often irritated reading the manual for a piece of electronic gear made in China that is all too often difficult to translate. It is written in Chinglish and for some sentences I have to pause and try to comprehend. I usually just make a mental Scooby Doo sound and move on to the rest of the manual.

7 Killer Tips For A Successful Specification Document:

1. Time is of the essence..
Evaluate the amount of time that is being put into the overall project, and then determine what portion of that should be focused on the spec sheet. For a brief document, 15 to 30 hours might be enough (15 pages and 3 to 4 wireframes), but a more detailed sheet takes no less than 50 hours. The time spent on the document should be proportional to the budget. There needs to be a conversation about how much time you can realistically devote to the specifications so that the rest of project can proceed in a smooth and prompt manner. If the project has only 400 hours allocated, it doesn’t make sense to spend 100 hours writing the specs.
- See more at: http://www.bluefountainmedia.com/blog/how-to-write-a-specifications-document/#sthash.tndl8JeY.dpuf

7 Killer Tips For A Successful Specification Document:

1. Time is of the essence..
Evaluate the amount of time that is being put into the overall project, and then determine what portion of that should be focused on the spec sheet. For a brief document, 15 to 30 hours might be enough (15 pages and 3 to 4 wireframes), but a more detailed sheet takes no less than 50 hours. The time spent on the document should be proportional to the budget. There needs to be a conversation about how much time you can realistically devote to the specifications so that the rest of project can proceed in a smooth and prompt manner. If the project has only 400 hours allocated, it doesn’t make sense to spend 100 hours writing the specs.
- See more at: http://www.bluefountainmedia.com/blog/how-to-write-a-specifications-document/#sthash.tndl8JeY.dpuf

7 Killer Tips For A Successful Specification Document:

1. Time is of the essence..
Evaluate the amount of time that is being put into the overall project, and then determine what portion of that should be focused on the spec sheet. For a brief document, 15 to 30 hours might be enough (15 pages and 3 to 4 wireframes), but a more detailed sheet takes no less than 50 hours. The time spent on the document should be proportional to the budget. There needs to be a conversation about how much time you can realistically devote to the specifications so that the rest of project can proceed in a smooth and prompt manner. If the project has only 400 hours allocated, it doesn’t make sense to spend 100 hours writing the specs.
- See more at: http://www.bluefountainmedia.com/blog/how-to-write-a-specifications-document/#sthash.tndl8JeY.dpuf

7 Killer Tips For A Successful Specification Document:

1. Time is of the essence..
Evaluate the amount of time that is being put into the overall project, and then determine what portion of that should be focused on the spec sheet. For a brief document, 15 to 30 hours might be enough (15 pages and 3 to 4 wireframes), but a more detailed sheet takes no less than 50 hours. The time spent on the document should be proportional to the budget. There needs to be a conversation about how much time you can realistically devote to the specifications so that the rest of project can proceed in a smooth and prompt manner. If the project has only 400 hours allocated, it doesn’t make sense to spend 100 hours writing the specs.
2. Don’t dive in head first.
Before getting too excited and diving directly into the detailed specifications, spend some time visualizing the new website as a finished product. Consider how you want the most important pages to look, then start drawing out their structures and drafting wireframes. You don’t want to make everything up as you go along, so taking the time to create a skeleton of how you imagine your site looking can make the rest of the process much more organized. Only start working on the specs when you have a clear picture and long term goal for the whole project.
3. Home is where the start is.
The homepage will be the first thing most of your audience sees upon visiting your site. So when working on wireframes, this is the logical place to start. It should include links to all important sections of the website. Once the wireframe of the home page is completed, the process of working on the other sections becomes much easier.
4. Understanding is in the details.
Let’s say you are outlining a redesign for an existing website. Make sure you take the time to learn how all sections of the old website work first. In the long run, you’ll be very happy you did. If old sections are cut or left out, the corresponding or replacement sections on the new site should be addressed accordingly. This is also important when redirecting old URLs that may be linked to from outside sources.
5. Not making a decision is a decision - a bad one.
Why make a plan, if the plan is incomplete? Do not leave any empty sections that you intend to wait and make a decision on later. Make sure that the spec document covers all sections of the website. If there is anything that is unclear, come up with a list of questions for the client that is filled with topics you would like to address. The goal you set should be laid out as clearly as possible because it will make your job, and the client’s involvement, a much smoother process.
6. Make the possible, possible.
Empty promises lead to hard feelings. You won’t feel good about them, and neither will the client. During the planning process, make sure the site functionality options described on the spec document are actually feasible. Having to go back to the client with any issues later on can leave them incredibly disappointed.
7. Keep it simple.
Most clients are not going to have in-depth knowledge of HTML, JavaScript, etc., so you should make an effort to ensure this document is as clearly laid out for them as possible. A client might believe they understood what you said, but often what they heard and you meant, were two completely different things. It may feel tedious, but it can help to avoid any possible misunderstandings down the road.

Delivering the Deliverables

A well-crafted specification document allows designers and developers to move forward with a project while avoiding any surprises for the client down the line. It should give a precise estimation for a timeline of the project, and a completion deadline. You can hold you and your team accountable, while keeping the client at bay with an indication of what tasks you’re working on and when. This helps to control the scope of the work, and keep costs from increasing throughout development. It is important to keep these details in mind while building a strong foundation for your overall project. In the end, it will lead to smooth communication between you and your client, and a clear picture for the project ahead
- See more at: http://www.bluefountainmedia.com/blog/how-to-write-a-specifications-document/#sthash.tndl8JeY.dpuf

7 Killer Tips For A Successful Specification Document:

1. Time is of the essence..
Evaluate the amount of time that is being put into the overall project, and then determine what portion of that should be focused on the spec sheet. For a brief document, 15 to 30 hours might be enough (15 pages and 3 to 4 wireframes), but a more detailed sheet takes no less than 50 hours. The time spent on the document should be proportional to the budget. There needs to be a conversation about how much time you can realistically devote to the specifications so that the rest of project can proceed in a smooth and prompt manner. If the project has only 400 hours allocated, it doesn’t make sense to spend 100 hours writing the specs.
2. Don’t dive in head first.
Before getting too excited and diving directly into the detailed specifications, spend some time visualizing the new website as a finished product. Consider how you want the most important pages to look, then start drawing out their structures and drafting wireframes. You don’t want to make everything up as you go along, so taking the time to create a skeleton of how you imagine your site looking can make the rest of the process much more organized. Only start working on the specs when you have a clear picture and long term goal for the whole project.
3. Home is where the start is.
The homepage will be the first thing most of your audience sees upon visiting your site. So when working on wireframes, this is the logical place to start. It should include links to all important sections of the website. Once the wireframe of the home page is completed, the process of working on the other sections becomes much easier.
4. Understanding is in the details.
Let’s say you are outlining a redesign for an existing website. Make sure you take the time to learn how all sections of the old website work first. In the long run, you’ll be very happy you did. If old sections are cut or left out, the corresponding or replacement sections on the new site should be addressed accordingly. This is also important when redirecting old URLs that may be linked to from outside sources.
5. Not making a decision is a decision - a bad one.
Why make a plan, if the plan is incomplete? Do not leave any empty sections that you intend to wait and make a decision on later. Make sure that the spec document covers all sections of the website. If there is anything that is unclear, come up with a list of questions for the client that is filled with topics you would like to address. The goal you set should be laid out as clearly as possible because it will make your job, and the client’s involvement, a much smoother process.
6. Make the possible, possible.
Empty promises lead to hard feelings. You won’t feel good about them, and neither will the client. During the planning process, make sure the site functionality options described on the spec document are actually feasible. Having to go back to the client with any issues later on can leave them incredibly disappointed.
7. Keep it simple.
Most clients are not going to have in-depth knowledge of HTML, JavaScript, etc., so you should make an effort to ensure this document is as clearly laid out for them as possible. A client might believe they understood what you said, but often what they heard and you meant, were two completely different things. It may feel tedious, but it can help to avoid any possible misunderstandings down the road.

Delivering the Deliverables

A well-crafted specification document allows designers and developers to move forward with a project while avoiding any surprises for the client down the line. It should give a precise estimation for a timeline of the project, and a completion deadline. You can hold you and your team accountable, while keeping the client at bay with an indication of what tasks you’re working on and when. This helps to control the scope of the work, and keep costs from increasing throughout development. It is important to keep these details in mind while building a strong foundation for your overall project. In the end, it will lead to smooth communication between you and your client, and a clear picture for the project ahead
- See more at: http://www.bluefountainmedia.com/blog/how-to-write-a-specifications-document/#sthash.tndl8JeY.dpuf