LSL / Maintenance notes

Software engineering / Maintenance notes

Care for what
already works.

Practical notes for maintaining software: understand the current behaviour, make a bounded change and leave the context the next person needs.

Open the maintenance guide →
An original maintenance map connecting a source, a small change and its review record Three paper-like panels overlap a green circular frame. A fine line carries context from the first panel to the last. SOURCE / CHANGE / EVIDENCE / CONTEXT
A maintenance trail: keep the source, the change and the review connected.

01 / Read before revising

Begin with behaviour
you can establish.

A maintenance task often arrives as a short request. Before choosing an implementation, make the request and the current path understandable enough to discuss.

Keep uncertainty in the record. The work can begin with a focused question; it does not need a complete model of the system.

Read the notebook approach →
Behaviour
Describe what happens in the relevant path. Keep the observed result distinguishable from the result described in an old note or expected by the request.
Boundary
Name the part of the system and the user journey involved. Record what this change will leave alone so review can focus on a clear question.
Source
Keep the request, relevant code and supporting material close to the working record. Note where a description needs further confirmation.
Responsibility
Identify who can clarify the intended outcome and who will review the change. A technical question and a product decision may need different people.

02 / Worked example

One message, two meanings of “saved”.

Consider a settings panel that changes a local value and shows a success message. The maintenance question is whether that message describes the local update or a completed persistence step.

Establish the current meaning

Trace the path that produces the message. Identify which state it follows and what evidence would show that the underlying operation completed. Keep a remembered explanation separate from the path you actually establish.

Bound the proposed change

The proposed change is to make the message reflect the agreed completion state. Updating the storage implementation or changing the data format would be separate decisions unless the investigation shows they are necessary.

Write the question before the patch

Which signal makes the message accurate, and which other paths rely on the state being changed? Answering that question gives implementation and review a common reference.

  1. 01 / COMPLETION

    What event makes the message true?

    Locate the signal that supports the new wording. A local update, a submitted request and a confirmed result are different states; establish which one the interface is describing.

  2. 02 / INTERRUPTION

    What happens when completion is delayed or fails?

    Review the relevant paths without assuming the successful path explains them. Keep the intended message, available user action and observed result together in the check record.

  3. 03 / CONTEXT

    What changes when the person leaves or repeats the action?

    Examine the conditions relevant to this interface. A repeat action or a changed view may expose another assumption about who owns the pending state.

  4. 04 / SCOPE

    Which result belongs to this change?

    Connect each check to the agreed boundary. Record a separate finding when the investigation reveals another issue, then decide explicitly whether it changes the scope.

04 / The handover is part of the work

Leave a shorter search
for the next person.

A change record can explain why the patch exists without retelling every working conversation. Preserve the decision, the relevant evidence and the points that remain open.

Place operational instructions in the project’s actual runbook. The maintenance note can connect to that source in the working system instead of creating a second, drifting copy.

A compact maintenance memo

Reason
The behaviour being clarified and the source of the intended outcome.
Boundary
What the change includes, what it excludes and any scope decision made during the work.
Evidence
Which checks were completed, under what conditions and with what observed result.
Remaining work
The unresolved question or separate finding, with a responsible person and a clear next step.

One bounded change can leave the system easier to understand as well as different in behaviour.

Use the maintenance change guide →