{"id":1725,"date":"2026-11-20T01:40:00","date_gmt":"2026-11-20T01:40:00","guid":{"rendered":"https:\/\/cotocus.cn\/blog\/blank-page-diagnosis-swipe-file-for-engineering-write-ups\/"},"modified":"2026-11-20T01:40:00","modified_gmt":"2026-11-20T01:40:00","slug":"blank-page-diagnosis-swipe-file-for-engineering-write-ups","status":"publish","type":"post","link":"https:\/\/cotocus.cn\/blog\/blank-page-diagnosis-swipe-file-for-engineering-write-ups\/","title":{"rendered":"Why Every Document Starts Blank, and the Swipe File That Fixes It"},"content":{"rendered":"<p>The symptom is easy to recognise. A pull request lands with a one-line description. A design note arrives as a wall of text. A handover document leaves out the one thing the next person needs. Nobody is lazy; everyone is simply starting from a blank editor, and a blank editor produces whatever the writer happens to remember on a tired afternoon. This post diagnoses why that keeps happening in engineering and training teams, and proposes a small, cheap fix: a swipe file of strong technical write-ups.<\/p>\n<h2>The symptom: every document is invented from scratch<\/h2>\n<p>Picture a team on a Thursday evening. A release is due, and someone has to write the change description. They open the form, see an empty box, and type the first thing that comes to mind: &#8220;fixes the thing&#8221;. Next week another engineer gets confused by the change and spends an hour reading code that a decent paragraph would have explained in two minutes.<\/p>\n<p>Multiply that by every pull request, every diagram, every runbook and every post-incident note. The cost is not dramatic on any single day. It is a steady tax paid in questions, delays and avoidable misunderstandings.<\/p>\n<h2>The diagnosis: nobody ever saw a good one at the right moment<\/h2>\n<p>When people are asked why their documents are thin, the answers are rarely about skill. They say there was no time, no one asked for more, or they were not sure what &#8220;good&#8221; looks like here. The last answer is the interesting one. In most teams, strong examples exist, but they are scattered across old tickets, chat threads and forgotten wiki pages. At the moment of writing, nobody can find them, so nobody imitates them.<\/p>\n<p>Three root causes tend to appear together:<\/p>\n<ul>\n<li><strong>Invisibility.<\/strong> Good examples are not collected anywhere, so new joiners never see them.<\/li>\n<li><strong>No stated standard.<\/strong> Quality lives in people&#8217;s heads, which means it differs from person to person and drifts over time.<\/li>\n<li><strong>Cost of starting.<\/strong> An empty page is expensive to begin; a half-shaped page is cheap.<\/li>\n<\/ul>\n<h2>The fix: a swipe file, kept small and annotated<\/h2>\n<p>A swipe file is a short collection of documents you admire, saved with a note on why each works. For an engineering or training team, a sensible first version has four shelves: change descriptions, architecture sketches, runbooks and post-incident write-ups. Put three or four strong examples on each shelf. Under each, write two lines. What does this document do well? What would we borrow next time?<\/p>\n<p>Be concrete in the notes. &#8220;Great PR description&#8221; teaches nothing. &#8220;States the problem before the change, lists what was deliberately left out, and says how to test it&#8221; is a checklist someone can follow. After a few weeks of this, your collection quietly becomes a living style guide, written from your own best work instead of imposed from outside.<\/p>\n<h2>Applying it: what happens on the next Thursday evening<\/h2>\n<p>Return to the tired engineer with the empty box. This time there is a link in the template: &#8220;Examples we like&#8221;. They open the shelf, read the two-line note about the clearest change description, glance at the example and write their own, using the same order. It takes five minutes longer than &#8220;fixes the thing&#8221; and saves everyone downstream far more than that.<\/p>\n<p>The trainer preparing a workshop does something similar with course outlines. Before drafting, they read three saved outlines and the reasons they work: a clear outcome at the top, short practice blocks, a closing recap. The new outline is fresh, with new material, yet it rests on a layout that real learners have already tested.<\/p>\n<h2>Where to find material worth saving<\/h2>\n<p>Start inside your own organisation, because those examples fit your context. Then look outward. Our own pieces on <a href=\"https:\/\/cotocus.cn\/blog\/deep-dive-the-complete-engineering-blueprint-for-web-project-requirements\/\">putting together a thorough requirements blueprint for a web project<\/a> and on <a href=\"https:\/\/cotocus.cn\/blog\/questions-to-ask-before-building-a-custom-web-application-the-complete-guide\/\">the groundwork questions worth answering ahead of a bespoke web application<\/a> show the level of structure that makes a requirements document easy to review, and either would earn a place on the &#8220;design notes&#8221; shelf.<\/p>\n<p>It also pays to peek at fields that have nothing to do with software. A flight-and-space themed training-style site such as <a href=\"https:\/\/www.astropilot.co\/\">AstroPilot<\/a> divides its pages into pilot courses, licences and a blog, and the plain, parallel labels are a handy reminder of how a broad curriculum can be made scannable. You are borrowing the shape of the navigation, not any aviation content.<\/p>\n<h2>Guardrails so the fix does not become a new problem<\/h2>\n<p>Three guardrails keep the habit healthy. First, cap each shelf. When a stronger example arrives, retire a weaker one. Second, never use the file to copy wording; the point is to learn structure. Third, strip anything sensitive. Saved documents should be free of credentials, customer details and internal hostnames, and where an example is too revealing, save a redacted version or a description of its outline.<\/p>\n<p>Give the collection an owner who rotates every quarter, so it does not depend on one enthusiast. The owner simply tidies the notes and hosts a brief review where the team chooses one new addition.<\/p>\n<h2>What a good note sounds like<\/h2>\n<p>The quality of the whole collection rests on the notes, so it is worth practising them. Compare two versions for the same saved architecture sketch. The weak note says: &#8220;Clear diagram.&#8221; The strong note says: &#8220;Shows only the components involved in this one flow, labels each arrow with what travels along it, and puts the external dependency in a different shape so you can see where control ends.&#8221; Anyone reading the second note knows exactly which habits to copy.<\/p>\n<p>A useful drill is to write each note in the form &#8220;this works because&#8230;, so next time I will&#8230;&#8221;. The second half forces a decision. If you cannot complete it, you have not understood the example yet, and the entry is not ready to be filed.<\/p>\n<h2>Handling the objections you will hear<\/h2>\n<p>Teams usually raise the same three worries. The first is time: &#8220;we are too busy to curate&#8221;. The answer is to save only when you are already writing a document, so that curation rides on existing work. The second is originality: &#8220;we will end up sounding alike&#8221;. In practice the opposite happens, because shared structure frees people to put their effort into the content, where individual judgement shows. The third is maintenance: &#8220;it will go stale&#8221;. It will, unless you give it an owner and a review rhythm, which is why the guardrails above matter as much as the collection itself.<\/p>\n<h2>Bringing it into training sessions<\/h2>\n<p>If you teach, the swipe file becomes a teaching aid as well. Hand learners two saved documents, one strong and one weak, and ask them to explain the difference in their own words. Then ask them to rewrite the weak one using the strong one&#8217;s structure. This exercise teaches more about clear technical communication in an hour than a long lecture can, because learners see the pattern, name it and apply it within minutes.<\/p>\n<p>Encourage participants to start their own personal collections during the course. Those who leave with a small, annotated set of examples carry a practical reference into their first projects, and they are more likely to keep refining it than people who were only handed a list of rules.<\/p>\n<h2>Signs that the diagnosis was right<\/h2>\n<p>Within a few weeks you should notice changes. Review comments shift from &#8220;what is this for?&#8221; to &#8220;could this be tighter?&#8221;. New joiners write passable first documents without being coached line by line. People start nominating examples unprompted: &#8220;that handover was great, can we save it?&#8221; When that last one happens, the swipe file has become part of the team&#8217;s culture and no longer needs a champion.<\/p>\n<p>If none of this happens, check the usual suspects. Is the collection easy to reach from the places where writing happens? Are the notes specific? Is the library small enough to skim? Fix those and try again for another month before drawing conclusions.<\/p>\n<h2>A short summary of the cure<\/h2>\n<p>The problem: documents are written from nothing, so quality depends on memory and mood. The cause: good examples are invisible and the standard is unstated. The remedy: a compact, annotated collection of the best work you can find, linked from the places where people write. The result: faster starts, clearer documents and fewer questions later. Setting it up takes one sitting and keeping it alive takes minutes weekly, which is a bargain for something that improves every document your team writes from then on.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Thin pull requests and patchy handovers usually trace back to blank-page starts. A small annotated swipe file of strong write-ups is a cheap, practical cure.<\/p>\n","protected":false},"author":4,"featured_media":1726,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[331],"tags":[],"class_list":["post-1725","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-devsecops"],"_links":{"self":[{"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/posts\/1725","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/users\/4"}],"replies":[{"embeddable":true,"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/comments?post=1725"}],"version-history":[{"count":0,"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/posts\/1725\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/media\/1726"}],"wp:attachment":[{"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/media?parent=1725"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/categories?post=1725"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/tags?post=1725"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}