Good designs generally reflect the nature of the problem they solve, and the same applies to designing a process for design. Design is messy, incremental, and has spurts of both broad and deep exploration.
Here I’ll describe the simple and flexible organization structure my duck docs evolved to capture design thoughts for reference without impeding exploration.
UPDATE: I’ve updated some of my duck doc structure
The organization scheme consists of two main mechanisms: sections and tags.
The sections largely reflect steps of design, but also a few frequent-reference items.
- Motivation: Every doc starts with a high-level motivation statement. It’s important to know the why behind the work so that the right problem is solved. This section is a great place to link pre-existing materials for the task
- Requirements and constraints: Starts breaking the motivation down into a checklist of success criteria. Could also be considered a “definition of done”.
- Exploration (a.k.a. knowns and unknowns): This section is the meat of the document. Questions and facts are collected until there is a clear enough picture to make a solid plan
- Plan: Outline the conclusion of the explorations. Often a checklist. Makes an easy reference for implementation and future readers.
- Implementation: Additional details and problems always show up during implementation. This section is a scratch pad for modifications to the plan
- Meta: I also usually include a yaml section at the top with date, author, and work item information for clerical purposes.
Textual tags tame the tangle, providing enough structure to reference key pieces of information without pulling the author out their rapid flow of thought. Tags only require a local decision and can be backfilled easily
My duck docs have refined a fairly small but powerful set of tags over time.
- Q: / A: -> Question and it’s answer. Deliberation may come in between, usually as bullet points
- Q: / OPT: / DECIDED: -> Question, Option, and the final decision
- Similar to question and answer, but oriented to questions that have limited answers categories
- PRO: / CON: -> State advantages and disadvantages of each option
- U: -> Unknown. A statement of some quality that I don’t know, but think is important.
- K: -> Known. For recording facts about the problem
- REQ: -> Requirement. Mostly used to mark new requirements discovered in the flow of exploration. These should be copied up to the requirements section at a convenient time.
- SOURCE: -> some reference used to inform the design or a question.
- PROBLEM: / OPT: Very similar to Q:, but used for unforeseen issues in a previous decision rather than general exploration. Also usually phrased as more of a statement about current behavior than a question. A good way to get unstuck.
The Exploration and Implementation section are usually just a nested list of questions. The additional tags help index the raw chain of thought, simplifying reference to previous decisions, sources, and alternatives.
You don’t have to tag everything. Tag things you want to be able to find later. For example,
- newly discovered requirements or constraints
- decisions about the solution
- the conclusion of a line of questioning
- and key pros or cons of alternate approaches
It’s best to get your thoughts out there, and tag them later if they end up being important.
Textual tags are a much more general pattern. You can read about similar techniques here
Here is an actual example from a learning project of mine. The stakes were low and the goals loose. Thus, I don’t dive deep into many of the questions.
The design process is messy. The thought process is fast and loose. However, well chosen sections and textual tags can meet the design process in its natural state and provide enough order to speed continuing work.