From 33 Specs to 20: Fixing Documentation Sprawl Before It Rots
Photo by Cup of Couple on Pexels Last week I opened my app's spec folder and counted the files. Thirty-three. For an iOS app built by one person. Fifteen of them were shorter than 55 lines. Three described quick capture — separately. One existed purely to document UI I had already deleted. The folder had become a museum of decisions instead of a description of the product. This is the story of…
In an iOS app built by a single developer, the spec folder had ballooned to 33 files. Of those, 15 were shorter than 55 lines, and three each described capturing a task or a haptic feedback, separately. One file was dedicated solely to documenting UI elements that had already been removed. The spec folder had transformed from a clear description of the product into a museum of decisions.
The sprawl happened gradually, with each feature leading to a new spec. If a task could be captured inline, a new spec was created. The same applied to capturing tasks in different lists, adding haptic feedback, or implementing animations. Each file made sense at the time it was written, but the problem lay in what they described: events, not things.
For example, "completion-animation" described an event that occurred once, whereas the developer needed a "completion experience" that included the animation, haptic feedback, and delayed exit.
The documentation sprawl was insidious because each individual file appeared fine on its own. The real issue lay in the aggregate. Andy Hunt and David Thomas, in their book "The Pragmatic Programmer," state that "Every piece of knowledge must have a single, unambiguous, authoritative representation within a system." This principle, usually applied to code, is equally crucial for documents.
The rule that fixed the grouping was to organize specs by capability, not by change. A capability represents something the product does, while change refers to something that happened once. In the case of the iOS app, completion animation and completion haptic feedback were not two capabilities but two requirements of one capability: the experience of completing a task. Similarly, quick capture could occur in various contexts, not as separate capabilities.
After reorganizing the specs, the folder reduced from 33 files to 20. Contextual task creation, list inline capture, and upcoming inline capture became separate specs, as did completion animation and completion haptic feedback. Daily reorder, custom list reorder, and task actions were grouped together, and list management specs like list delete, rename, and reorder were also consolidated. Two specs were moved to existing files, two were deleted, and 13 remained unchanged.
The consolidation process focused on verification rather than writing. Every requirement title needed to be listed exactly once, and the number of scenarios per target file had to be reconciled. Dead weight, such as obsolete or removed features, was deleted last. The result was 20 well-organized specs, each with a clear purpose and no redundant information.
To prevent the same issues from reoccurring, the developer implemented several rules. New behavior should be added to an existing capability spec unless it genuinely represents a new capability. New requirements should not automatically lead to new files. The spec folder should be pruned on a regular basis, with deleted specs for removed behavior and overlaps flagged for merging.
Sprawl is easier to manage monthly than it is annually. The specs should be indexed by domain, with a single README mapping each spec to its area to facilitate navigation even as the number of specs grows again. Lastly, formatting should be normalized whenever a file is edited.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
