Project documentation: How a ‘how-to’ can ensure success

In a recent issue of WServerNews, our popular weekly newsletter, I talked about why large IT projects often fail. This led to some lively discussion from our readers, but it also got me thinking. Could it be that poor documentation practices might be one of the contributing factors to the failure of many IT projects? To gain some insight into this matter, I reached out to John Citron, who worked for many years in network administration and IT support and has been involved in numerous infrastructure upgrades, migrations, and rollouts. While John is now retired and spends his life studying music and enjoying other hobbies, his IT world began nearly 40 years ago as a PCB assembler, where he soon moved up and outwards after taking classes in analog and digital electronics. John says he was never really interested in this field initially, but fell into it and remained there for the rest of his working life. At one point he even worked for some of the now long-gone early hardware manufacturers including Visual Technology, Infinet, and Datawatch. As a technician responsible for repairing early personal computer systems, he learned MS-DOS and CP/M, and later took programming classes in Z80 and 8080 assembly. Once the technician jobs disappeared, John landed in MIS and computer operations where he ran computer rooms full of DEC VAXs running VMS and Ultrix, Sun OS systems, and even a smattering of IBM MVS/TSO, OS/2, ROSCO, and later Solaris and Novell Netware. As time moved on and the industry moved from centralized operations to the workgroup environments, John moved with that trend, and after spending time with the family graphics business as a typesetter using a proprietary Varityper Epics 20/20 system and working in network administration and desktop support, he finally retired in 2012. So I can safely say that John’s knowledge and experience in the fields of IT and project management are both deep and strong. Let’s now turn the floor over to John and hear what he has to say about how documenting IT projects the correct way can ensure success.

Documenting IT projects: How to do a good how-to

Documenting IT projects

Writing how-to documentation for IT is a much neglected and overlooked step to ensure the success of projects, and also products. Documenting IT projects, whether for internal use or for an end-user, will ensure that processes and procedures are consistent, and all parties involved will use the same process, which makes everyone’s life easier as this cuts down on support calls and allows projects to move along in an efficient manner. Having everyone working off the same page when doing things ensures that the project will move along no matter who is tasked for the job, and in some instances, this also allows job-sharing and job-coverage, which ensures a continuity in projects should a teammate be out of the office during that time.

Sadly, in many cases, especially within the IT world, documentation is the last thing on anyone’s mind. Software developers almost never think about the end product, and when the product is released, the end-user is left scratching their head as they figure out how to use the product.

With that in mind, why not buck that trend and put things in writing? But documenting IP projects requires a consistent process in itself. Many years ago, I worked as a computer operator with very complex daily operations. In order to ensure that each process was done consistently and exact every time, procedures were set up. As time went on, the various operators would come up with their own methods of doing things. This caused errors and outright failures as steps were overlooked or forgotten.

I was tasked with writing up the how-to documents for each and every job we ran on a daily basis, as well as maintaining the document library, and updating the check-off sheets that we followed to ensure the jobs were done in order. In the end this worked out well, as the department was able to maintain a 98 percent success rate. Out of that big project, which was done nearly 30 years ago now, I’ve since been the one tasked to write up how-to documentation. Even today in my retirement, I still get asked how to do things, and still today put together step-by-step processes for documenting IT projects. As seen below, the parts are pretty simple, though the process can be time-consuming depending upon the complexity of the end-product:

  1. Establish a document-revision system.
  2. Use a template.
  3. State an overview.
  4. Create the step-by-step process.
  5. Test the procedures.
  6. Have someone or a group unfamiliar with the process test the procedure.
  7. Test again.
  8. Release the document for use.

1. Establish a revision system for the documentation

Depending upon the organization or situation, this may be done using a system all unto itself. There are some documentation systems set up that will automatically create revision and version numbers as well as archives. For other situations, having a simple date-stamp with a rev number may suffice.

For example, in one organization where I worked we had a document server, which date-stamped and created all the version numbers for us. In another workplace, I simply used DD-MM-YY — Rev X with the documentation name in the document template footer and document name.


04-08-2017 — Rev 2.1 — Installing Service Alliance

2. Use a template

As I hinted to above, having a specific format for documenting IT projects keeps the procedures consistent throughout. The template will also ensure that specific information is included in the procedures. There’s an added benefit, too, as this makes the process so much easier than starting everything from scratch. Having that layout planned out ahead of time means there’s one less thing for us to think about in our busy IT lives.

3. State an overview

No matter how simple a process may be, it is recommended to give the end user an idea of what they’re going to achieve.

4. Create the step-by-step process

There is no need to go into too much detail, but too little detail is not good either. Striking that right balance may have to do with the intended audience, and or the complexity of the product or process. There will be cases where a specific step needs explanation in details.

Divide the process up into as many steps as necessary. Keep in mind the intended audience. Just because you know how to check your browser security settings, for example, doesn’t mean everyone does. If you’re writing stuff for your teammates, you can probably leave these details out, but if you’re creating a handout for the end-users, something such as this is necessary.

When writing, use pictures if possible. With the invention of screen capture utilities such as the Windows Snipping-tool, Snagit, or other similar tools for other platforms, we have no excuse not to include pictures or diagrams with our documentation. Use a word processor such as Apache OpenOffice Writer or Microsoft Office, or whatever is available on the platform you are using. These programs have that ability to insert in-line screenshots with subtitles, and run-around text features. Having the screenshot within the text, and not plopped at the bottom the page, keeps the document together. There’s nothing worse than having to flip through multiple pages back and forth to refer to an image. The means that the documents are released have changed much since 1992 where we used a text-only system! With today’s online medium, HTML-formatting, wiki-formatting, and so on, you have at your disposal many venues for your opus, so make use of this capability.

5, 6 and 7. Test, test, and test

Test, test and test

Much like software development, documenting IT projects requires testing and checking. This ensures that the process not only works, but it also makes sense to the end-user. Once the documentation is written up, go through the procedures yourself. Look for typographical errors and check for procedural errors. Your proofing and checking, however, is a superficial one. Once the obvious kinks have been removed, have someone else who is not familiar with the process look over the procedures. This step will allow a fresh set of eyes find the holes and kinks that you’ve missed yourself. In some scenarios, it may be necessary to hand off the docs to a group of users. End users are particularly good at finding stuff.

Again, much like software development, this beta-testing phase requires updates to anything found by the tester or test group, and then checking documentation again. This can take a few go-arounds in some cases, depending upon the complexity of the project.

8. Release the documentation

The documentation may need to be signed off on by various parties. In the computer room job I had, all users had to sign off on the documentation, which meant they had read through the work and note any necessary changes. Once signed off, the documentation is ready for prime time, as they say. The end users — the recipients of your hard work — now have the documents in their hands. This doesn’t mean the process is complete, however, and the document will eventually make its rounds through the process again, much like software, as changes and updates are needed.

Writing up and documenting IT projects, whether for internal use or for an end user, will ensure that processes and procedures are consistent and all parties involved will use the same process, which makes everyone’s life easier as this cuts down on support calls and allows projects to move along in an efficient manner.

Photo credit: Pixabay

About The Author

Leave a Comment

Your email address will not be published. Required fields are marked *

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

Scroll to Top