
New engineers are often told to “document your decisions,” which sounds sensible and tells you almost nothing about how. This primer narrows the advice to one very practical piece: writing down assumptions. You will learn what the term means, what a good entry contains and how to start on a real ticket tomorrow. Towards the bottom you will find a short word list, handy when colleagues drop these terms into code reviews.
The basic idea in one paragraph
Whenever you design or change something, you rely on facts you have not checked. The disk has space. The other team’s service answers quickly. Your colleague will review the change this week. Most of the time these beliefs hold, and that is exactly why they are dangerous: you stop seeing them. Writing down assumptions means dragging them into the light, saying how sure you are, and noting how you could find out if you are wrong.
Why beginners benefit more than experts
Experienced engineers carry a large library of “things that usually go wrong” and check them by reflex. You have not built that library yet. A written list lends you the reflexes of someone more seasoned, because every time you write “this will probably be fine,” you pause long enough to ask whether it is. It also gives reviewers something concrete to react to. A reviewer who sees your list can say, “I would worry about the third line,” which is far kinder to a newcomer than discovering the problem in production.
Where to put the list
Place it where the work lives. In a ticket, add a section headed “Assumptions.” In a design document, add a short table. In a pull request, add a paragraph in the description. The location matters less than the habit of putting it somewhere another person will see it.
How to write one entry
- State it as a full sentence. “The staging cluster has the same version of the database as production,” not “DB version.”
- Say how sure you are. Use plain words: sure, fairly sure, guessing.
- Name a check. A command to run, a person to ask or a page to read.
- Record the outcome. When you check, write what you found and the date.
No special tooling is involved; a plain text file is enough.
A small worked example
You are asked to schedule a nightly backup of a small application database. Before starting, you write:
- Backups can run at night without affecting users. Guessing. Check: ask the team when traffic is lowest.
- There is enough free storage for a month of copies. Fairly sure. Check: look at current usage and estimate growth.
- The restore process has been tried at least once. Guessing. Check: ask who last restored from a copy.
- Credentials for the backup job will not expire during the month. Fairly sure. Check: look up the rotation schedule.
Four lines, five minutes, and you already hold three small errands that could prevent a bad night. The restore question is especially valuable; many people only learn whether a backup works when they need it.
What assumptions are not
Beginners sometimes blur three neighbouring ideas, so it helps to separate them. A fact is something you have verified; it needs no entry. A requirement is something the work must achieve, set by someone else. An assumption sits between the two: you are treating it as true to get on with the work, but you have not checked. If you can quickly turn an assumption into a fact, do it and write the result next to the line. If you cannot, leave it on the list until you can.
How long the list should be
For one ticket, three to six lines are usually plenty. If you find yourself writing fifteen, the ticket is probably too big and deserves splitting. Another good sign that you are overdoing it is that you start listing things nobody could ever test, such as “the internet will keep working.” Stay with beliefs that would change what you do if they proved false.
Handling a wrong assumption gracefully
Discovering a mistaken belief means the list is working as intended, and nobody should read it as a black mark. Cross out the line, write what you learned, and note which parts of your work it affects. Tell your reviewer in a sentence. Most teams are glad to see a newcomer catch their own error before anyone else does, and the habit builds trust faster than a flawless first month would.
Mini-glossary
- Assumption: a belief your plan depends on that you have not confirmed.
- Constraint: a limit you have been given and cannot change, such as a budget or a deadline. Different from an assumption, because nobody expects it to be tested.
- Confidence: your honest sense of how likely the belief is to be true.
- Check: the smallest action that would settle the belief.
- Owner: the person responsible for running the check.
- Trigger: an event or date after which you will look at the assumption again.
- Dependency: something outside your control that your work needs, often the source of an assumption.
Where this fits on a career path
Habits like this are what turn a junior engineer into someone colleagues trust with larger changes. A guide to the typical progression from junior to senior DevOps roles describes the technical milestones, and a record of clear thinking is a useful companion to them. If you are moving across from a support or systems administration background, the article on changing direction from sysadmin or support work into DevOps covers how your existing experience carries over; much of it already includes unwritten assumptions that you can now put on paper.
Common beginner mistakes
- Writing tasks rather than beliefs. “Install the agent” is a task. “The agent supports our operating system version” is an assumption.
- Giving everything the same confidence. Variety is the point.
- Never going back. An unchecked list is just a diary.
- Hiding the list from reviewers. Showing it is the whole benefit.
Other places to read about it
Handbooks, internal wikis and training websites all touch on the subject. One site worth a glance is NoOpsSchool from India, which on its own pages puts forward certification courses alongside consulting and service offerings for people in IT. Use outside material to broaden your vocabulary, then settle on a format small enough to maintain every day.
Your first assignment
Pick the next ticket you receive. Before writing any code or running any command, write five assumptions about it and add a confidence word to each. Check the two weakest. Paste the results into the ticket and ask your reviewer which line they would have worried about. Whatever they say will teach you something about how experienced colleagues think, and you will have started a habit that is easy to keep and hard to regret.