Documentation Structure

Our software project documentation evolved over the last years towards a setup where you have a “Products” section and a “Projects ” section.

Projects section

This is where we started, it made sense to cluster work in a timely context. A context means, what am I trying to achieve, how long should it take, what is my plan of attack, who is involved, when are we successful. In other words, making a project of it.

Projects can range from weeks to months and longer. I know there is a whole part of the world moving away from projects at this moment in time but frankly, I do not agree. Having this project container makes a lot of sense to me and it forces you to think about the goal and plan upfront. Of course, there is no way you can write a plan at the beginning, and never have to change it along the way… But now you can document the reason for the change together with the change in that project container. This also holds true for a goal and people involved etc…

When working this way a lot of things start to fall into place.

• What are we trying to achieve?
• When are we succesful?
• Who is working on this project?
• Where do I put the minutes of meeting?
• Where can I find the minutes of meeting?
• We need to onboard a new team member, where should he start?

Product section

This is were we capture the overarching “products” where we are working on. A product is not finished in one project. It might take months/years and might never be finished or at least it might take constant improvements.

So a product is achieved by executing multiple projects. But what you do not want to have is searching for valuable information on a product in all the projects you have ever run. To side step this issue we move all relevant information to the product level. So at every moment in time we all know what the current/actual documentation is for this product.

PARA

We iterated this way in the last years and then my colleague, Rob, came with this interesting find: PARA.

PARA stands for Projects, Areas, Resources, Archive. So apparently someone on the other side of the world faced the same issues and had a similar solution to it… how interesting! We looked at PARA and have now adopted this way of organizing digital information. We did not have to change much so that was easy.