Project Documentation? Aah, that’s a tedious, painful task. These were the exact words in my mind, whenever there was any discussion about it. And sadly, the situation is still the same haha.
There are always 2 sides of a coin. Same applies to getting organized too. The good side makes you document things so it helps you in future, the bad part is, “you” have to do this job.
Frankly speaking, we were totally messed up when we started. Things were moving smoothly as we had a small team but as we started growing, we realized that we were missing many important documents. The missing documents were making our life miserable as we had to spend lot of time explaining the new guys about the on going project and tasks.
We had things in place but everything was scattered. I knew that we badly needed to get organized but I was staying away from making lengthy documents with too much information. Everything was so complicated.
I decided to prepare a set of documents which will be simple and serve the purpose too. Obviously, there is no rocket science in this. It’s basically set of documents created based on what I have read and understood by going through many project documents.
Let’s talk about the project documentation for dummies.
What all information do we basically need to know about the project?
- Core documentation of the project
- Details of each and every module we have worked on
- Details about table structure and changes
- Team members who were responsible for the modules
- Learnings from each module (This helps to improve ourselves in future)
So, this is what I came up with:
Following folder & file structure:
- Change Log
- Module Name
- Module Screens
- Technical Details
- Table Structure Changes
- Staff Involved
- Closure Report
- Work in Progress (Same folder structure as the folder “Module Name”)
Now, let’s to through every folder and file to understand purpose of it in detail.
Core: I have first created a folder called Core, which will have all the core documents of the whole project. In my example, I have just used a document which summarizes the whole project but you can add documents based on your requirements.
Core / Details.doc: This document contains technology details, version history, milestones, team members involved, objective and scope of the work. Basically, this will be the main document which will help end user to understand working of the whole project.
Versions: This folder will contain sub folder for each version. You can decide whether you want to add minor versions here or not. I would prefer adding major versions here. (1.1, 1.2 etc..). Let’s take a look inside version 1.0.0’s folder.
Versions / 1.0.0 / Changelog.doc: As the name suggests, the document basically contains changelog of the module. Fixes, additions etc.. You can skip this documents if you are generating changelog from any project management or any versioning application.
Versions / 1.0.0 / Module Name: The name of this folder should be replaced with the actual module name which was included in the version. You should have different folder for every module you have worked on in that particular version.
Versions / 1.0.0 / Module Name / 00 – Screens /: This folder is basically used to store the module screens in image format. This will help you to understand screens involved in that particular module change.
Versions / 1.0.0 / Module Name / 01 – Details.doc: This document will have the details related to the changes. This is not a technical document so basic information related to scope should appear here. I have divided this document in 2 scopes. Original Scope and Final Scope. Original Scope is basically actual requirement and Final Scope will have the finalized requirement. This will be same in most cases but sometimes, you end up modifying few things which affects the original scope.
Versions / 1.0.0 / Module Name / 02 – Technical Details.doc: This document will have all the technical details related to the module. You can provide technical flow of the changes. Changes in the classes, functions etc..
Versions / 1.0.0 / Module Name / 03 – Table Structure Changes.xls: This excel sheet should have all the database changes which are made for this particular module.
Versions / 1.0.0 / Module Name / 04 – Staff Involved.xls: This document will have list of all the team members with their roles in this module and the period they have worked for this module.
Versions / 1.0.0 / Module Name / 05 – Closure Report.doc: This is most important part of the project. This is basically a document containing questions related to quality of the work, following timelines, performance of team members, learnings from the mistake etc..
I have also created a folder called Work in Progress. This folder will basically have the folders for modules your team is currently working on. The logic is, you work on the documents in Work in Progress and move the documents to Versions folder once you have deployed the changes on production server and tagged those changes under any version.
I have shared all the files with you guys so it can help you with the projects. You can download the archive containing all the files from here. I have tried my best to keep the minimum documents. But at the same time, I have made sure that, the documents cover the purpose of organizing things and provide required information to understand the project.
Like always, I am open to any suggestions.
I hope this helps you in some way.
I work for Times of India – Modernisation Department, and currently working on a Materials Management System (Inwards and outwards) which is on the platform of JSP/Servlets and back end of Oracle DB. Thank you, Mr. Deep for this documentation guide. 🙂 This is going to help me a lot in making of my documentation for this current project. Actually, thanks to Twitter so that I got to read your blog. 😉
Looking forward for more guidance in this field of Information Technology as this one from you. 🙂
I may need Project Documentation for my professional purpose very soon. Appreciating your effort which I certainly think will provide a lot of assistance for me then.