Ghost in the Pixel

As the spec writing process starts to gather steam, routine check-ins and reviews need to occur to ensure accuracy, and more importantly, capture any missed issues or conflicts/confusions with other members of cross-disciplinary team, particuarly QA or Development.

The reviews are not a time to go through word by word every single line or what’s written, nor is it a time for “committee writing”–simply unproductive! Instead, the weekly reviews should be a time to identify major issues that cropped up during the writing, gaps/deltas, and potential conflicts with what’s been prototyped vs. developed or tested. High level issues should be surfaced and debated, not tactical tweaks.

Before the weekly reviews, the spec writer should be in constant touch with the designers and QA, having a tight feedback loop on getting inputs, making sure changes to the design are communicated, etc.

UI specs should capture the following pieces of data: consistent terminology, pixel-level measurements, annotated screenshots (see prior post on how to create accurate images for specs), behavioral descriptions beyond the obvious or “for free” stuff, with cross-references where appropriate and useful between depedent specs.

Tables and spreadsheets do NOT make for good spec content or layouts as they tend to be hard to read.

Indeed, specs should be considered “designed artifacts”, not simply last minute or post-mortem writing thrown together at the end of a prototyping phase. Per schedules, the spec writing should occur somewhat in parallel, with engagement with the spec writer and devs, QA, UI designer, prototyper, etc.

Chunking and spacing the text and imagery properly is necessary to achieve that delicate balance of creating a document that is easily scannable and comfortable/inviting to read at length. Extensive prose text is not recommended. Avoid “should”, “could”, “would”, and any explanations/rationale–this is not a defense but a statement of what is to be. In effect, a recipe or cookbook so that if a disaster wiped out the company, then a remote dev team can rebuild the product from the specs (presuming that the documents are backed up somewhere!)