This is a summary of the main article, the real article goes into more details

Two weeks ago I wrote an article about governance and documentation on an organisational scale. This is the follow-up post that focuses on the project scale. You could just read this post, but it’s probably better that you start with the previous one first

For me, there are four main areas to support a (large) project. You require the Strategy, the foundation where you start and what the idea of the project is. The Logs, these are living documents that capture what is going on. Blueprint, these are mainly diagrams to support the project visually. And finally Program Management, where you keep everything that’s related to timing and execution.

Strategy

All of this starts with a Business Case. The “Why” we are doing this document. This can be high level, or very deep.

You will also find a Kick-off document here. These are often PowerPoint slides that define the team, scope, way of working, and timelines.

Logs

I always like to have an Open Questions Log. A centralized document (everyone has access) to questions that need answers.

The Decision Log is where you keep track of the closed questions. Again, very handy in an ongoing project, but extra useful once the project is over and it all becomes part of the bigger documentation.

Meeting Notes are also handy to store here, probably best in a subdirectory. AI-generated documents are actually very welcome here (compared to other AI generated documentation everywhere else)

Blueprints

I like to keep my diagrams both in the raw format (visio, draw.io, lucid,…) and in static formats (like PNG). I always like to have diagrams that show both the Target and AS-IS states, and if it’s a big project, what the project phases look like

Project related documents

I always like a Gantt Chart. Make sure it’s up-to-date and accessible to everyone. Ideally you also have the Critical Path highlighted. Also, deadlines and gates should be present. Providing a central Gantt chart ensures that project management is democratised.

The most important ones

You pick and choose what you think is essential in the scope of the project. You can also add more later.

That being said I like to always have at least the core documents. Even if it’s a project for an app that will be live for two weeks.

• The Business Case: If this isn’t clear, the architecture will drift.
• Decision & Question Logs: These are the most valuable “historical” nodes for future maintainers.
• TO-BE Diagram: A quick reference for everyone on what’s actually changing. Also, easy to copy and paste into presentations for higher-ups.
• The Gantt: That’s just basic project management and keeps everyone honest.

Merging it back into the bigger documentation

The diagrams can move towards the resources section with links to the applications.

Going over the logs, you can remove the noise and keep the logs that are relevant to processes and applications to the logs of those processes and applications.

You end up moving the rest to the archive section as a project folder. It’s very essential to not just delete here. If you have a similar project in the future, you can copy a lot of homework here.

Organic documentation

So these are my current views on documentation. To paraphrase this article and the previous one:

Small documents that are interconnected. Accessible and owned by everyone. Organically grown and mainly written from a project perspective.