Documentation for Engineering Projects and Future You

You solved the problem. You know which file changed, why the setting matters and what the test showed.

Six months later, you open the project again.

Unfortunately, future you wasn't at the meeting either.

This is why documentation matters. It gives the next person a way to understand the work without having to reconstruct every decision from the beginning.

Sometimes that next person is you.

Start with the questions the record needs to answer

Before creating another document, ask what someone will need to do with it.

Understand the design? Repeat a test? Maintain a system? Review a decision? Continue the work after a handover?

Those purposes need different amounts of detail.

A short decision record can explain why an option was chosen. A test procedure needs the conditions and steps required to produce meaningful evidence. A handover needs the current state and what happens next.

“Document the project” is too broad to guide any of those jobs well.

Make the current state easy to identify

People need to know what they are looking at.

Give the record a clear title, date, revision and owner where appropriate. Identify the equipment, software version or configuration it describes.

Then make it clear where the authoritative record lives.

A folder full of files called final, final2 and final-really-this-time gives future you a puzzle before the engineering work can even begin.

Follow the project's document-control process. Personal notes can help you think, but they shouldn't quietly become a competing source of truth.

Capture the reason behind the decision

The finished drawing shows what was selected. It may not show why.

Write down the requirement, the main alternatives considered and the constraint that made the difference.

For example: “Option B was selected because it maintains access during the required maintenance window. Option A met the performance requirement but required an outage.”

That sentence gives a later engineer a reason to keep or revisit the choice. If the constraint changes, they know what to reconsider.

Separate facts, assumptions and open questions. Don't let an assumption become an apparent requirement simply because it survived several copied documents.

Keep test evidence attached to its context

“Test passed” is a conclusion. Someone reviewing it needs to know what was tested.

Record the intended result, the setup, the version under test, the actual observation and any exceptions. Include the date and the relevant evidence reference.

If a screenshot matters, explain what it demonstrates. If the test was limited to a simulation or a bench setup, say so.

A result from one environment may be useful evidence without proving the whole operational system is ready.

That distinction saves later readers from making stronger claims than the test supports.

Use a drawing when relationships matter

A simple diagram can explain interfaces, boundaries and dependencies more clearly than a page of prose.

Label the connections and identify what sits outside the scope. Keep the diagram consistent with the detailed record it summarises.

The drawing doesn't need to be elaborate to be useful. It does need to tell the truth about the arrangement.

If you're drawing during a conversation, capture the agreed result afterwards. A photograph of a whiteboard is a start, but unexplained arrows and initials may not survive very long in someone else's memory.

Leave a proper handover

Before you put the project down, record what is complete, what remains unresolved and the next useful action.

Include known limitations and who owns each open item.

“Waiting for feedback” is less useful than “Interface review sent to the controls lead; response required before the configuration can be finalised.”

If someone takes over tomorrow, they should be able to work out where to begin and what decisions they are authorised to make.

For a broader reference, NASA's Systems Engineering Handbook section on technical management places technical data and configuration management within the project lifecycle.

Review the document as a user

Ask someone who didn't create the record to use it for a small task.

Can they locate the current drawing? Understand the decision? Find the test result? Identify an unresolved issue?

Where they hesitate, you have a useful improvement to make.

You don't need to add pages automatically. Sometimes the fix is one missing reference, a clearer heading or removing an obsolete copy.

Help future you get back to work

Good documentation makes it easier to act on what was learned.

Start with one decision or test from this week. Record the context, the evidence and the next step. Put it where the project expects to find it.

Then look at it as if you had never seen the work before.

If you want a place to capture working sketches before they become formal records, explore our engineering notebooks. The notebook can hold the thinking; the controlled project record needs to hold the agreed result.

Listen to the original podcast discussion