Project Diary

Context

You are working on a software project and need to track your progress.

Problem

How can you keep track of and document your progress in a moldable development project?

Forces

— It’s boring to write documentation after the fact.

— Documentation is not part of the running system, so it distracts you from coding.

— Tools for tracking your progress are separate from the code base, so they are commonly out of sync with reality.

Solution

Use a live notebook as the starting point for all tasks.

Steps

Create a dedicated notebook page for each project, or even each project task, to summarize the goals, and provide pointers to related material. Use the notebook to keep a diary of your progress. As the project matures, use the notebook as a draft for the documentation.

Examples

Below we see a live Lepiter page in the GT Book documenting the task of adding some list views to the Ludo game. This page started as a Project Diary page, and was later rewritten as documentation.

If needed, add a code snippet for any setup tasks ( e.g. , cloning repositories or loading databases). Add code snippets to the notebook pages to serve as moldable objects to start coding from. Extract interesting code snippets as example objects to document interesting use cases, or to serve as tests.

As the project grows, organize the notebook into a main page with an overview, and separate notebook pages for different tasks or groups of related tasks.

Consider using notebook tags to organize your pages implicitly. For example, use a dedicated project tag for all the project pages, and additional tags to indicate their status (“todo”, “completed”, ”urgent” etc.). For example, the “DRAFT” tag is used to track pages of the GT Book itself that require further editing.

At the end of a project, consider recycling and rewriting the project pages to create documentation. In this way the diary can serve as a rough draft.

Consequences

A live notebook is an integral part of the project, and evolves together with other software artifacts.

Notebook pages can express tasks in various stages of completion, so can be used as starting points for further development tasks.

Notebooks can serve not only to track progress, but also as documentation for both technical and non-technical stakeholders.

Known Uses

A Zettelkasten is a traditional form of note-taking, where notes are cross- indexed in card files using various metadata, to be used as a knowledge base for research and writing.

Jupyter notebooks are commonly used as both activity logs and as project documentation.

Personal knowledge management systems like RoamResearch are regularly used for diaries for software projects.

Related patterns

A Project Diary page can embed numerous live Example Object instances to document specific points.