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, so it is rarely done. 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.

Use the notebook to keep a diary of your progress. As the project matures, use the notebook as a draft for the documentation.

Steps

Create a dedicated notebook page for each project to summarize the goals, and provide pointers to related material.

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.

For an example, see Implementing a Ludo Game as a moldable development exercise. This is the starting page of a Project diary for the Ludo Game. The pages initially tracked the development steps of the project, and contain snippets from which to continue development. As the project came to an end, the pages were edited and rewritten to serve as documentation.

Related patterns

A project notebook page should contain snippets to create Moldable Object instances that can be used as starting points for Moldable Development.