Skip to content

Worklogs

Worklogs are dated entries — similar to blog posts — that capture what we did on a given day, what we learned, and what's next. They serve as a running record of development activity, decisions, and reflections.

Why We Keep Worklogs

  • Transparency: Anyone can follow the project's progress and understand the reasoning behind decisions.
  • Continuity: When picking up work after a break, the most recent entry provides context.
  • Accountability: Time and effort are tracked in a lightweight, human-readable format.

How We Manage Worklogs

Worklogs here are created with worklog-opsdevnz — a Python CLI tool published on PyPI that generates dated Markdown entries from a per-project configuration file.

# Install
pip install worklog-opsdevnz

# Create today's worklog in $EDITOR
worklog-opsdevnz

# Override the editor for this entry
worklog-opsdevnz --editor code

Configuration lives in a worklog.toml at the repo root — it sets the directory structure, section headers, author, and tags. Any project can adopt the tool by adding its own worklog.toml.

History

The worklog pattern has been used across OpsDev.nz projects for some time, starting as ad-hoc scripts that created dated Markdown files from a template. An earlier prototype lives at scripts/worklog.py and has since been superseded by the published worklog-opsdevnz module.