How to organize your project documentation (naming convention, storage location, order… No software, just methods)
“Yeah, just have a look on the specifications… They’re on the shared drive, or in your mails. And the title of the document is… Specifications_v1.1_draft(3).doc”.
Wow wow that doesn’t sound good. Unreliable revision located somewhere in several copies… to fix that you only need a couple of management rules and pretty simple methods. Together, let’s see what they are…
Vocabulary
Before going further, let’s check some definitions of concepts we mention in this article:
Request for proposal (RFQ)
This is the document where the customer lists all the requirements describing his need.
Peer Review
It is a review made by someone with similar skills that will be able to validate the technical content.
Never start from scratch
You very rarely do something for the first time. When was the last time you did something for the first time?
So avoid as much as possible starting your document from a blank page. Have you already written such a document for a previous projet? Or better, is there a document you can reuse the content from?
If the answer is yes to one of these questions, then find this archive, make a copy of it, it will be your starting point. It has probabely paragraphs or even complete sections you can reuse as they are. Or those contents, reusable or not, will be a good baseline to kickstart your documentation.
If the answer is no to both, no worries, there are plenty of template online (check fyi for example). We, Naept, even provide some documentations templates for free here.
Where to save your documents
This seems to be a commonplace, but I ensure that if you think through it, a good place to put all your documents can save you a lot of time and ease the teamwork.
Rule #1: Never save your document on your computer desktop.
Rule #2: Never save your document on your computer desktop.
There is no more dangerous battlefield than a crowded computer desktop (except a real one off-course).
Coworkers may contribute to the document?
Then go directly save it somewhere reachable for them: a shared folder, in the cloud, on OneDrive, Sharepoint, Google Drive…
Do you have a usual folder tree structure to sort your documents? Some folder architecture telling where to store each kind of file for a projet? If yes, use it. If no, here is one
Template for project documentation folder architecture
Here is a template to manage all the documents about one specific project. In this example, I will focus only on project documentation. But you can easily expand this template by adding other folders to manage product or user documentation.
The projects folder
Here I take the example of my 47th project entitled “Project_X”.
Rule #3 : save all the projects in the same folder.
(I’m going to give a load of rules, but actually you obviously do as you want. Those suit well my work habits and make me more effective. But take them, adapt them, twist them, make them your own.)
Personnaly, all my project ar located in D:\Mes_Projets (because I’m french).
Rule #4 : no space, accent, or special caracters in the folder or file titles.
Some applications I use cannot read them and so cannot load file pathes. In the past, I happened to have to rename all my files in some projects. #NoMore
All my old “spaces” are now underscores.
Rule #5 : index all the folders.
It is another obsession but I prefer my folder to be chronologically sorted than alphabetically. So I always create a new project next to the last one, I can duplicate the most recent architecture. Besides I usually reuse the same documents over and over from a project to another, so I know where to find the most updated ones.
In a project folder
Here, for any kind of project, I always have at least those 2 sub-folders:
- 00_Inputs
I store all documents required to kickstart the project. These are all the “source” or draft documents that come from out of the project. - 10_Outputs
This is where I save all the project specifically made documentation that will come and goes out of the company, to the customers, to the suppliers, etc. This is where I shall store the request fo proposal, the specifications…
I index all the sub-folders from ten to ten (00, 10, 20…). It leaves me space to create folders in between others just in case.
In 10_Output
We are getting close to the request for proposal!
Here I create one new folder for each output document.
In the example, there are one for the request for proposal and one for the specifications. In reality, there are way more documents such as conception requirements, validation plans, functional tests, integration tests… But their managements are the same, so I just limit the example with 2 of them.
I usually add two more folders with a slightly different content but useful to all:
- 98_Bibliography
Here I put external and reference documents that can be mentionned in the project’s such as standards, reference articles, datasheets… The difference with 00_Inputs is thin but yet it exists. For exemple an early description of the need at the project core will be located in 00_Inputs, but the datasheet of a specific device used to build the solution, and called in several documents, will be store in 98_Bibliography. - 99_Images
This is where I gather all the figures, illustrations, icons, drawings that can be used and diplayed in the outputs to describe their content. As we can reproduce the same drawing from one document to another, it is bette to collect them in the same place than to copy / paste them in all the document folders.
The indexation of those last documents is very high (98 and 99) so they stick at the end of the folder list and not amongst them. So I can always find them in a glimpse.
In 10_Request_for_proposal
Finally! This is where you will store your precious document! (In the exemple we talk about the RFQ but that just a decoy to represent any of your documents).
But not only!
So here you store your working document: for each document, you have a unique file you will modify, correct and improve during the projet. Regularly you will make copy of it to freeze every of its revisions.
Indeed, your RFQ, and by extension every output document, is supposed to evolve: you will write a first draft that will be peer reviewed then you’ll all some corrections to make. You’ll come up to a second revision to be sent to your customer or suppliers. Eventually they’ll have their own remarks to be taken in account in a third revision. And so on.
You will have to keep track of every modifications to get a unique source of truth on the project, that is why many revisions need to be frozen as pictures of the project. That is what we call documentation management.
Typically, everytime the working document is ready to be communicated to someone (an internal reviewer, a customer…) a copy shall be made. This copy represents the revision “vX” and SHALL NOT BE ALTERED AT ANY CONDITION (so it is better to make it a PDF document). Then you can tell the reviewer which revision to check so you know exactly what he reads.
To do so, I suggest to create a folder “vX” for every major revision. A major revision is a revision that is sent out of your company to a customer, a supplier, a partner… This “vX” folder will contain all the inbetween revisions that lead to the major one, all the frozen revisions for an internal review for example. Here is an illustration to explain it:
Exemple :
D:\My_Projects\047_Project_X\10_Outputs\10_Request_for_proposal\
Request_for_proposal.doc (<- that’s the working document that only the author can modify)
v1\
Request_for_proposal_v0.1.doc (<- this is the first minor revision)
Request_for_proposal_v0.2.doc (<- this is a second minor revision)
Request_for_proposal_v1.doc (<- this is the first major revision)
v2\
Request_for_proposal_v1.1.doc
How to name it?
Now we know where to save it, can we give it a title a little bit more effective?
Until now, we did entitle it “Request_for_proposal_v1.doc”. It seems to be rather correct and to be honest it will be perfectly satisfaying 90% of the time.
So a simple question: what if despite your excellent folder architecture, you have so much folder that you don’t want to browse them to find the document. You can still ask the search engine to find it. But problem, all the requests for proposal of all your projects have the same name! Now you have to open each of them to find the right one.
Here are some more tips to try.
What do you think of this document title: NPT_PROJECTX_RFQ_v1.doc ?
Let’s break it down:
- “NPT”: at Naept, this is the trigram representing the company name. So if I send an RFQ with it to our supplier, he’ll know in an instant where it comes from.
- “PROJECTX”: this one is rather obvious, it is the name of the project. Lucky me, in the example, the project name is already short. But if it’s too long, we can come up ith an abreviation or an acronym : PX, PRX, ProjX. Putting the name of the project within the title of all its documents allow to find all the project documentation with only one search!
- “RFQ” means… wait for it… Request for proposal. It is shorter like that. You have to know that file path can be limited in character, so you’d better keep them as short as possible.
- “v1” and finally the revision index, but you already know that.
So long story short, this new title means “ Here is the first revision of the request for proposal from the company Naept about the Project X “. This long sentence is now encoded in only 19 character, easily understandable by a human and a search engine.
Make this naming convention your own and don’t forget the share it with the people reading your documentation so they don’t get lost.
Conclusion
Et voilà!
You now have a fully structured project repository with structured named files. We are know able to adresse the structuration of the content of your document.
But what if I told you it exists an even better way to manage your project documentation with free open-source software? This will be for a future article. Stay tuned!
What about you?
How do you manage the storage of your documents?
What software solutions do you use?
Do you have specific naming conventions for you fils?
📝 Contribute to our Study of documentation on business projects.
