Improve your project docs with journalling

You have better things to do than write and maintain long documents that rarely get read. I have used strong words to share my dislike for documentation in the past, and I still feel the same way today.

Yet here I am, asking you to write more. A whole lot more. Please. Bear with me. It is not documentation per se, and you do not have to maintain it!

Let me introduce what I call project journalling, and share how this has helped me to keep sane across tens of parallel projects.

I want to show how we can remember, report, and think better by writing less, but more frequently.

I believe this is a trend now as more teams move toward working remotely. When working remotely, documentation and writing become far more critical. Especially when team members are online at different times during the day.

Do not throw away your documentation

Project journalling is not a replacement for traditional project documentation. Specifications, project timelines etc.

Added though, it can reduce the need for formal documentation. Since everyday decisions and discussions are logged and archived where they do not need to be updated later or touched again.

Budgeting, resource lists, how-tos etc., are still essential and must be kept up to date. I propose a separate list of notes documenting why certain things were updated in these other documents.

This means we can keep the other documents free of discussion and have them contain only the conclusions.

Add journalling

To better track why a budget came to be or a design was decided, I add lists of dated updates to the projects.

Modern documentation portals such as Confluence or Notion offer excellent support for adding pages under other pages. These, in turn, document the timeline of each “project”.

Note that I use the term “project” loosely here. It could be anything.

This structure can benefit non-projects like your hiring process guide or the documentation for a product’s system or workflow.

However, I have seen this structure explode with too many top-level parts. So I prefer to keep documentation under each project as they create obvious boundaries of what goes in under a project or not.

When journalling under projects it is clear that any changes that belong to that project are documented under the project. Once the project is closed, a new project will be needed if more changes or updates are to be documented.

But even after a project closes, I usually add follow-up documents for measurements and results, saving them to the same project.

Example of a company directory structure in Notion
Example of my how I organise project journalling in my company document structure

The simplest structure is a date and a name

For every day and new topic for a project, be it a design review, business rule discussion or other meeting agenda, I add a page under the project page dated and named.

Two document structures side by side, one from Notion and one from Confluence
Example of two projects I’ve used journalling of, both on Notion and Confluence

The date helps create a logical structure and timeline and avoids duplicates.

For example, 2022-08-14 Design review is much more likely to be unique than only Design review. Keeping pages uniquely named is even required in some systems (Confluence).

Having the name helps search for the most recent and relevant data.

Finally, humans relate very well to spatial hints. That is, we remember where things are if we can relate the placement to something else.

Most people use calendars daily, and dating the documents creates really good relative anchors to remember where (or when) you saved things.

For example, if you remember roughly when you talked about something, you can search for your document by the date.

Tips to journal better

What do I journal?

Pretty much everything. It can be things I work on myself, in the group, or in meetings. Also, good writing is good thinking. Putting things in text allows us to see them again from a different angle.

Adding visuals and links is also an incredibly effective way to tell a story.

Although I think the format matters far less than the habit of noting things down, I follow a format like the one below.

Example of a journal page
Here is a rough example of how I might break down one of my journal pages

I always write who is involved and who the document is intended for. Lastly, I sum up the contents for quicker consumption and clarity. For meetings, if there are actions or conclusions, these are most important to note.

Without clear conclusions and ownership, things fall between chairs. With modern document portals, adding references to your teammates also usually sends them an update or alert; that way, you get a progress update done for free.

You can copy my example page from Notion.

But again, the format is less important than the habit of writing down the thinking and conclusions.

How project journalling can help you

  1. You have a record of decisions
  2. The flow describes not only the conclusions but the causes leading to them
  3. Splitting documents by date and topic creates a timeline of the project
  4. It becomes a free archive of documentation that need no updates
  5. By tagging your coworkers, they are automatically given reports on progress and can comment when needed

Convinced? If not, I hope at least you found some inspiration.

Do share if you have any comments or practices you have found helpful and thank you for reading!

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
David Dikman

Full-stack developer and founder. Writing here and at https://greycastle.se. Currently open for contract work.