Book Appointment

Assumptions Log FAQ: A Clinic Booking Tool Design Document

Healthcare Software

Software for healthcare offices, such as a booking form, a reminder service or a simple patient-queue display, is built on a stack of guesses about how the office actually works. A developer says “appointments are thirty minutes” long before anyone has asked the front desk. Here are straight answers to the usual questions about keeping an assumptions log in a design document or ticket, using a small clinic booking tool as the running example. Everything stays on the software and scheduling side; there is no clinical content and no medical advice.

What exactly is an assumptions log in a design document?

It is a short section, usually near the top, where the author lists the things the design depends on but has not confirmed. Each entry is a plain sentence. Beside it sit a confidence level and the way you would find out whether it is true. It is not a requirements list and it is not a bug tracker. It is a place for beliefs that could be wrong.

For a clinic booking tool, a first draft might read: “Every appointment slot is the same length.” “Only one person books at a time per slot.” “Patients can read the reminder text in the language we send.” “The clinic’s opening hours do not change between weeks.”

Why not just fold these into the requirements?

Because requirements are decisions and assumptions are guesses. A requirement says what the system must do. An assumption says what you are counting on being true about the world the system runs in. If you mix the two, a shaky guess starts looking like an agreed fact, and reviewers stop questioning it.

Keeping them apart also helps later. When something breaks in production, you can open the log and see whether a recorded guess failed or whether nobody had thought of the situation at all. Those two cases call for different fixes.

How many assumptions should a single document carry?

Aim for the ones that would be expensive to get wrong. For a small booking tool, eight to twelve lines is typical. If you are listing thirty, you are probably recording facts or trivia. A useful rule: if learning that the guess is false would force a change to the data model or the user flow, it belongs on the list.

What does a concrete entry look like?

Take this example. Assumption: two staff members will never edit the same day’s schedule at once. Confidence: low. Check: ask the front desk whether the lead and the assistant ever both adjust the calendar during the morning rush. Impact if wrong: double-booked slots unless the system handles conflicts.

That small entry, written before the first line of code, can save days. Had it stayed unspoken, the conflict would likely have shown up as an angry report from the desk, followed by an emergency patch. Written, it triggered a five-minute conversation and a decision to lock slots during edits.

Who should read and challenge the log?

Everyone whose work depends on the design: other developers, the person who runs the office day to day, and whoever supports the tool afterwards. Invite them to mark lines they disagree with. Disagreement is the point. The cheapest bug is the one a receptionist spots in a table of sentences.

Do I need special tooling?

No. A heading in the design document, a table in the wiki, or a checklist in the ticket is enough. Some teams like a template with five columns: statement, confidence, check, owner and result. What matters is that the log lives where people already look, and that you update it when plans change. A fancy tool nobody opens is worse than a plain list that everyone sees.

How do I rate confidence honestly?

Ask what you are basing it on. “I saw it last month” is stronger than “it seems likely”. A line backed by direct observation can be medium or high; one resting on habit or hearsay is low until checked. If you cannot articulate why you are confident, record low. It is a surprisingly effective discipline.

And if a guess fails?

Mark it failed, note what you learned, and adjust the design. Then look sideways: which other lines depended on it? Often one wrong guess quietly undermines two others. Record the correction with a date. Over time the failed entries make a useful teaching resource for new team members, because they show where the real office differs from the neat picture in a developer’s head.

Is this only for new projects?

No. Inherited systems benefit even more. If you take over a booking tool nobody documented, a good first task is reconstructing the assumptions: what time zone is stored, what happens at daylight-saving changes, what the system assumes about phone numbers. Treat the code as evidence and confirm each guess with the people who use the tool.

For related background, see our overview of how engineering services keep software and cloud operations tidy and a general guide to building a web presence with a content management system. Both sit in the technology part of this blog and are general reading.

Where does technical training come into it?

Engineers pick up the assumptions habit on the job, but some also seek structured courses. A website based in India, NoOpsSchool, whose own pages list certifications, courses and consulting for IT staff, is one such place; as always, read what a provider says about itself before deciding. The log itself needs no course. It needs a heading in your next design document.

Can you show the log changing a design?

Certainly. Suppose the log said that reminders go out the evening before an appointment, with medium confidence. A quick chat with the office revealed that early-morning slots matter most to them, and that families often travel in from other towns. The team moved the reminder time and added a second message two hours before the slot. No heavy analysis was needed, only a line on a page that invited somebody to say “actually, not quite”.

The change also left a trail. Six months later, when someone asked why there were two reminders, the answer sat in the log next to the original guess and the date it was corrected.

What are the common mistakes?

  • Writing vague sentences. “The system is fast enough” cannot be checked. “A booking page loads within a few seconds on the office’s connection” can.
  • Listing decisions as guesses. If the team chose it, it is a requirement.
  • Forgetting the check column. A guess with no test is only a hope.
  • Never revisiting the log. Update it at each milestone and each change of scope.
  • Hiding the log in a private file. Assumptions work best when others can see them.

Can the log help with estimates and deadlines?

Yes. Many slipped deadlines trace back to a handful of unchecked guesses, such as a partner’s interface being ready on time or test data being available. If those appear in the log with low confidence, you can build slack around exactly those items rather than padding the whole schedule. Stakeholders also respond better to “this date holds if these three things hold” than to a bare date.

Where should I begin today?

Open your current design document or ticket and add a section titled “Assumptions”. Write down five things the plan relies on that you have not verified. Add a confidence word and a check to each. Send it to a colleague and the person who runs the office. That single page is a complete start, and the rest of the practice grows from it.