<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Writer’s Blogk - Medium]]></title>
        <description><![CDATA[Notes from the technical writing underground. Journaling by a technical writer. - Medium]]></description>
        <link>https://medium.com/writers-blogk?source=rss----87cecf19207---4</link>
        <image>
            <url>https://cdn-images-1.medium.com/proxy/1*TGH72Nnw24QL3iV9IOm4VA.png</url>
            <title>Writer’s Blogk - Medium</title>
            <link>https://medium.com/writers-blogk?source=rss----87cecf19207---4</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 23:33:25 GMT</lastBuildDate>
        <atom:link href="https://medium.com/feed/writers-blogk" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[The Soiled Sheets Of A Writer’s Game]]></title>
            <link>https://medium.com/writers-blogk/blank-sheet-musical-sheet-the-soiled-sheets-of-the-writer-4910f9d98b18?source=rss----87cecf19207---4</link>
            <guid isPermaLink="false">https://medium.com/p/4910f9d98b18</guid>
            <category><![CDATA[writing]]></category>
            <category><![CDATA[music]]></category>
            <category><![CDATA[games]]></category>
            <category><![CDATA[sex]]></category>
            <category><![CDATA[romance]]></category>
            <dc:creator><![CDATA[Peter Villani]]></dc:creator>
            <pubDate>Fri, 26 Apr 2019 19:44:43 GMT</pubDate>
            <atom:updated>2019-04-09T20:13:02.446Z</atom:updated>
            <content:encoded><![CDATA[<h3>The Soiled Sheets of the Writer’s Game</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*RSqjfv1V2Rc7B1OB3ElLCg.jpeg" /></figure><p>Blank sheet. Reader clearly defined. Knows nothing about what I’m going to write. Is ready to stop the moment I say something that she —no, <em>he</em> — cannot understand.</p><p>My goal is to start with something familiar. Like sports. Then to go a bit deeper, to sing, he and I, reader and writer. And then to introduce a third person. When it all ends, she’ll be in bed while he continues to play some stupid game that has something to do with lifting things.</p><p>If that interests you, please read on.</p><p>Every game has rules. Otherwise, how do you play? Imagine a game with no rules. You pick up an object from the street, anything. Another person does the same. What’s the game? Whoever drops it first, wins. Or whichever object is bigger, or heavier, wins.</p><p>We can invent the game as we go along. I do something, you do something, and eventually we come up with a challenge to decide who wins and who loses.</p><p>The sheet is no longer blank. The reader is less defined. And I’ve soiled the project with this game digression. But I need to keep going.</p><p>Let’s see if every game needs a winner and a loser. If we change the above scenario, the one where two people pick things up and decide who wins and loses; if we remove the competition and we replace it with an activity that starts with <em>no</em> rules; for example, <em>he</em> does something and continues to do something while <em>she</em> does something else in parallel, or she does nothing but waits for a signal, or walks away and starts watching television; but whatever she decides to do, he doesn’t stop, he keeps lifting objects until finally she looks over and says “What are you doing”? This is the start of the game.</p><blockquote>Writing is about building something together. Win or lose. Build, alone or together. Create a problem, a mystery, a relationship; resolve it. These are all games people play. What game, then, do I want to tell my reader about? I started out with sports — so let’s say the field is wide open but there’s no goal.</blockquote><p>Does winning and losing help me tell the story? Does building, or mystery-solving, or even tongue-twisting add to my story?</p><p>Well it depends on what game I want to play with my reader. I’ll choose one that I know well. The game of music. The musical scale. My goal in this game, this story, is to teach you something about music.</p><p>A scale has 8 notes or 12 notes or “5 à 7” (as they say in French). A scale can also have as many notes as there are tones on an instrument. Or it can simply be described as any sequential series of notes played together. But let’s not complicate the subject before getting started. Let’s start with the most obvious scale, the Major C, the <em>do</em>. Seven notes.</p><p>Sing the familiar upward melody of the C-scale: <em>do-re-mi-fa-sol-la-si-do</em>. Play a game with them, where each note is a player: <em>do</em> is a player, <em>re</em> is a player, as are <em>mi</em> and <em>fa</em> and <em>la</em> and <em>si</em>. Seven players.</p><p>So who wins? What’s the game? The game is music-making. You need to write a song. The rule is to use only the Major C-scale—the one in the middle of the piano that’s played entirely with the white keys. The <em>do-re-mi-fa-sol-la-si-do</em> sequence.</p><p>Hands down, <em>do</em> is the winner. Of course. It all begins with <em>do</em>, it’s the root of the whole scale. The game, the whole tonal sound, begins and ends with the sound <em>do</em>. Try it out. Sing it. You can’t start a <em>do</em> scale at <em>la</em>, for example, without shifting into another scale, a more somber version of the <em>do</em>. So <em>do</em> wins.</p><p>But who comes in second? I’ll save you the time. In second place we have <em>sol</em>, and in third, <em>mi</em>. The top three notes of any scale are always in the first, fifth, and third positions. These three notes (<em>do-mi-sol</em>) form a triad. A triad forms the basis of all western classical and popular music. Sing them. You’ll hear completeness, perfect harmony, no dissonance. Not a song yet — thank god! — because we need tension.</p><blockquote>In our game, in music, everyone wins, everyone goes home with something. <em>si</em> is a winner if we want something romantic, fireside. <em>la</em> beats <em>si</em> for its melancholic and contemplative mood. Good jazz comes out of <em>re</em>. And let’s not forget <em>fa </em>for its rock-n-roll. At this point, the race is on, and <em>si</em>, highly competitive, skips the romance and cheats, slightly bending itself, transforming our song into some kind of blue.</blockquote><p>This is where the descent begins. We reverse the order of the winners, we put <em>do-mi-sol</em> behind us and put our hopes on any note that transforms us into the kind of song we want to sing.</p><p>That’s the game, music, he says, continuing to lift things and drop them while she’s already asleep. She’s no gamer, she couldn’t stay awake to make sense of it all.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Gmadt6GeYv5R_eZlpKuhhA.jpeg" /><figcaption><em>So what happened, here?</em></figcaption></figure><p>It started with a blank sheet and a potential reader. Now both of these are no longer the case — the sheets are soiled and the reader has long gone. One thing led to another. Seduced. Abandoned. A romantic touch, a bit of jazz, a melancholic mood.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4910f9d98b18" width="1" height="1" alt=""><hr><p><a href="https://medium.com/writers-blogk/blank-sheet-musical-sheet-the-soiled-sheets-of-the-writer-4910f9d98b18">The Soiled Sheets Of A Writer’s Game</a> was originally published in <a href="https://medium.com/writers-blogk">Writer’s Blogk</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[practicing clarity — is this a form of sanity?]]></title>
            <link>https://medium.com/writers-blogk/practicing-clarity-is-this-a-form-of-sanity-1329d12d9cf3?source=rss----87cecf19207---4</link>
            <guid isPermaLink="false">https://medium.com/p/1329d12d9cf3</guid>
            <category><![CDATA[technology]]></category>
            <category><![CDATA[writing]]></category>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[technical-documentation]]></category>
            <category><![CDATA[technical-writing]]></category>
            <dc:creator><![CDATA[Peter Villani]]></dc:creator>
            <pubDate>Thu, 07 Mar 2019 18:59:55 GMT</pubDate>
            <atom:updated>2020-08-20T14:14:29.123Z</atom:updated>
            <content:encoded><![CDATA[<h3>practicing clarity — is this a form of sanity?</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*IgEu2CpiokTwdCa8Ck8UiA.jpeg" /></figure><p>It’s hard to know where our professional persona ends and the rest of our bodies and minds (and souls, I guess) reside.</p><p>This presupposes that there is indeed a difference between who you are professionally and non-professionally.</p><p>In my case, this presupposition feels true on almost every level of my being.</p><p>For example, in my role as technical writer, I am constantly challenging my investment as a writer. I write and read all of the time — at work, at home, not at home not at work. Mostly fiction. Journaling all of the time.</p><p>So where does technical writing fit into this otherwise literary world? Here: somewhere between clarity and ambiguity.</p><p><strong>Start with Clarity</strong></p><p>I make a living doing only one kind of writing: creating technical content for developers, as well as other professionals who need to understand the technical nature of what my company offers. I make an effort to write in a language that anyone can understand, without dumbing down the material. Otherwise, I’d lose my main audience (developers).</p><p>However, I do try to write so that anyone can kick up their feet and enjoy reading my texts as long as they are OK with other signs of life on the page, such as code, diagrams, (some) technical jargon, and bullet points. That’s because the overall framework of the documentation I produce contains a sort of storytelling and uses everyday language to speak clearly and passionately about technology.</p><p>I write technical content with joy, first of all because I love writing, but secondly, in all my writing, clarity is key. Clarity reigns even when I am engaged in fiction or journaling or blog-journaling as here, where the material travels in and out of my rather active day-dream state. I consider all writing a process of making complexity clear.</p><p><strong>Add some ambiguity</strong></p><p>Making complexity clear in all its glorious goo is not only fun but necessary. But clarity does not exclude ambiguity. In my non-professional writing, I like being intentionally vague and filling my writing with loads of potential but unresolved meaning. I consider ambiguity as the best way to represent the false and unfounded but mostly true stuff that I encounter everywhere in the world, all of the time. (That may be just me, though..)</p><p>For me, acknowledging, writing down, and indeed creating ambiguity is a sure-fire way to get close to the real — <em>and</em> the clear.</p><p>But I would be a fool to believe that developers need ambiguity when reading about how to write great applications.</p><p>In my professional day job, therefore, ambiguity serves no purpose, or no <em>apparent </em>purpose. But I am a firm believer in that even in the most functional of writing, one must at least raise the ambiguity before undertaking a new assignment. There is no better way to know whether what you write will indeed be clear or complete or accurate. It will also help you contain an unconstrained, runaway idea liable to multiple interpretations, which can undermine your whole project, as well as create loads of support tickets.</p><p><strong>Finish with empathy</strong></p><p>Without knowing where ambiguity ends and clarity starts, how otherwise would you assess what your developer-readers’ are understanding or thinking about when they read your texts? How can you empathize with their confusions? We speak of being “concise” concise in technical writing, but concision does not, on its own, undo ambiguity. Otherwise it’s a dental <em>incision</em> — cutting too close, and cutting where it hurts.</p><p><strong>Ambiguity and its resolution creates a warm, cosy clarity</strong></p><p>Well anyway, like I said in the beginning, it’s hard to draw a line between the professional and the personal, especially when that line defines who you are within the highly-contoured world of your company’s products and bottom line — a line that often separates us from the rest of our tendencies …</p><p>But <em>practicing</em> clarity, as a form of sanity, makes it all seem OK to switch between the two.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1329d12d9cf3" width="1" height="1" alt=""><hr><p><a href="https://medium.com/writers-blogk/practicing-clarity-is-this-a-form-of-sanity-1329d12d9cf3">practicing clarity — is this a form of sanity?</a> was originally published in <a href="https://medium.com/writers-blogk">Writer’s Blogk</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Technical Documentation for the Hurried Polyamorous]]></title>
            <link>https://medium.com/writers-blogk/technical-documentation-for-the-hurried-polyamorous-23f84b3d90a3?source=rss----87cecf19207---4</link>
            <guid isPermaLink="false">https://medium.com/p/23f84b3d90a3</guid>
            <category><![CDATA[technical-writer]]></category>
            <category><![CDATA[technology]]></category>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[writer]]></category>
            <dc:creator><![CDATA[Peter Villani]]></dc:creator>
            <pubDate>Sun, 17 Feb 2019 23:54:33 GMT</pubDate>
            <atom:updated>2019-03-07T11:54:28.006Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*PdU4eNMBMjjM1zOpFaiuKg.jpeg" /></figure><p>People who come to <em>read</em> technical documentation are rare indeed. Most come with an urgent need to be guided, to be taken to where they need to go. On their way, they want to see as little noise (words) as possible. They are only happy when they see words like Exit, Pull, and Push — especially on doors obviously used for exiting which can be either pulled or pushed.</p><p>The learner-by-doing is looking for how to set something up, and where to put his or her code, and how to run it, and what kind of data to use, and why this error appears, and so on.</p><p>And who needs more than that? It’s love at first sight, so fast and blinding that he and she and he and he and she and they actually see nothing, not even each other, as they <em>do</em> only what they desire.</p><p>People are not coming to your words to read, but to use them as a tool. To turn a screw, open a car door, lift a hot liquid in small mouthfuls, and sneak a lick of chocolate at the bottom of the mixing bowl, a stolen pleasure savored in the moment before the next comes along.</p><p>This is what functional text should do: get people to do something with as little blocking the path to doing. Make it easy for people to take out their ruler, do a few measurements, and then screw or hammer away.</p><p>It’s that visceral.</p><p>I hate shopping malls. So I can’t think of a better experience than to be guided directly into a store, to a shelf, to the item, and then directly to the register, out the store, out the mall. Pure guidance. No time to think. No bothering with the noise of the winding halls of crowds and massive department stores. In and out in no time.</p><p>That’s what I like.</p><blockquote>A document that tells me <em>how</em> to do something is far more exciting than one that tells me <em>what</em> I am doing and <em>why</em>. Leave that up to me. That’s my thang. I just want to do. Give me the fix and the means to do it. Give me the installation, the data, the code. Give me pictures, the menu, and where to click my mouse. I want it to be tactile, immediate. I want to feel the sensation of completion. Done. Let me move on to another.</blockquote><p>Give me technical content that appeals to the hurried polyamorous.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=23f84b3d90a3" width="1" height="1" alt=""><hr><p><a href="https://medium.com/writers-blogk/technical-documentation-for-the-hurried-polyamorous-23f84b3d90a3">Technical Documentation for the Hurried Polyamorous</a> was originally published in <a href="https://medium.com/writers-blogk">Writer’s Blogk</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Writing only needs two dimensions]]></title>
            <link>https://medium.com/writers-blogk/software-documentation-is-geometry-4c152a92f64d?source=rss----87cecf19207---4</link>
            <guid isPermaLink="false">https://medium.com/p/4c152a92f64d</guid>
            <category><![CDATA[technical-writer]]></category>
            <category><![CDATA[writer]]></category>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[geometry]]></category>
            <category><![CDATA[creative]]></category>
            <dc:creator><![CDATA[Peter Villani]]></dc:creator>
            <pubDate>Fri, 08 Feb 2019 16:45:40 GMT</pubDate>
            <atom:updated>2020-08-20T14:11:11.783Z</atom:updated>
            <content:encoded><![CDATA[<h3>The geometry of technical documentation</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6m-e6AYTB9Txle5g6vgn3A.jpeg" /><figcaption>Software / API documentation is geometry</figcaption></figure><p>Software documentation is about building software, and building involves geometry.</p><p>For example, when you look at some common criticisms of documentation —</p><ol><li>“The text is not clear!”</li><li>“Information is missing!”</li><li>“The content is disjointed! No matter how much I read, I just don’t get it.”</li></ol><p>— you’ll see how thinking geometrically can solve these problems.</p><p>For the first two criticisms, you need only simple lines and squares. The third requires triangles and a bit more math.</p><h4>Writing horizontally — the sentence</h4><p>There is a <em>horizontal</em> component to writing an English text — horizontal in a purely left-to-right direction: the sentence.</p><p>We balance everything on that horizontal line. We leverage clarity, readability, and style. Spelling and grammar require zero height. For a line to remain single-dimensional, it must be concise, accurate, understandable, and unambiguous.</p><p>These are the basic axioms of <em>technical</em> sentences. Other forms of literature — like a novel — might drop the rule of non-ambiguity; poetry redefines or just ignores readability; etc.. But for a sentence to be successful within a technical document, it must follow this strict horizontal set of laws.</p><h4>Thinking diagonally — the paragraph</h4><p>The most perfect sentence does not always contain the best <em>content</em>. On its own, a sentence is abstract: It may be clear, readable, and so on, but it says nothing. A line is nothing more than syntax. And attaching lines within a single dimension merely extends the line off the page.</p><p>But when you start stringing <em>thoughts</em> together, you start switching direction, moving lines diagonally. Towards the paragraph.</p><p>Content — or meaning — breaks the one-dimensionality of the horizontal. Meaningful content <em>slants</em> the writer <em>and</em> reader away from the line: We must now get our text to say something — not only well or accurately — but meaningfully.</p><p>Consider this:</p><p><em>“ … judo experts searching for judo techniques might be most interested in advanced techniques … ”</em></p><p>Perfectly horizontal. But banal. It needs to be fleshed out. We need to start plotting points off the horizontal axis, to start attaching lines in all directions — up down sideways slanted. This is the second dimension.</p><p>What are the rules of the paragraph? Mostly the same — clarity, correctness, understandability — but it’s no longer about language. It’s about ideas and the order of those ideas. We ask, <em>Is the content — the concepts, ideas, facts — clear?</em></p><p>It’s also about readability and <em>reading</em> — Is the text engaging? Does it flow?</p><p>We write and read from sentence to sentence, from sentence to paragraph, from paragraph to paragraph. With this second dimension, our lonely sentence above is given meaning, context.</p><p><em>“The ideal of modern search is smart search — highly relevant results, tuned specifically for each user. For example, </em><strong><em>judo experts searching for judo techniques might be most interested in advanced techniques</em></strong><em>; beginners need to learn how to get started.”</em></p><h4>Documenting vertically — the page</h4><p>The page is the vertical component. While the horizontal and diagonal span in all directions, thus plotting our well-written ideas on a blank page, the end result is the page. The technical writer needs to be aware of the math: Does the sum of these lines (and spaces) serve the reader’s needs?</p><p>To start with: The page is greater than its parts. Perhaps we can add weight to our geometry: the weight of the sentences and paragraphs that inform the page.</p><p>With the page, we ask new questions. We look at the whole. We take a step back. Have we covered the subject? Let’s say we start our page with X and Y — when we reach the bottom, are we still talking about X and Y? have we said all there is to say about X and Y? Is the page self-sufficient, or is there something missing? Is there too much detail, is it too long? Maybe something can be removed, or a new page added.</p><p>Let’s look at the above text about Judo. But this time as part of the vertical order of the page. What is it talking about? “Search”? What is “modern” search? What is “relevant” and “results”? For the sentence to have its most successful impact, the page needs to create context (or at least point to where that context exists), and it needs to be conscious of its terminology and capacity / concerns of its readers.</p><p>The perfect page, however, is still not enough</p><p>Perfect as it is, we are not finished. The page — the vertical — raises other questions. <em>When</em> do we use the information on the page? Where does it fit in, in the larger whole? Should we do what the page tells us to do, and when? Are there alternatives?</p><p>Even more difficult are questions of <em>shared content</em>: Some paragraphs and pages relate to other paragraphs and pages. Should we break up the perfect page to favor other ways of organizing content, like centralizing information. And is it OK to sometimes repeat content?</p><h4>Beyond the page</h4><p>The breadth of technical documentation goes beyond the page, but it remains two-dimensional. Lines are not only about their own linearity — they also form squares, triangles, and circles — really useful geometrical two-dimensional objects that we can use to improve our documentation.</p><p>Before going there, let’s respond to some of the common criticisms mentioned at the start.</p><ol><li>“The text is not clear!”</li></ol><p>Text that is <em>Not Clear </em>can be resolved horizontally, with a bit of rethinking in the slanted diagonals. If you are asking, <em>Has this particular thought (paragraph) been clearly expressed?</em> That’s both a horizontal and diagonal concern.</p><ol><li>“Information is missing!”</li></ol><p>With <em>Missing Information, </em>we need to rethink the page, the vertical. The resolution is often a rewrite — adding text, removing text, re-wording, reorganizing. We need to focus on the lines, and their three directions — the sentences, paragraphs, and page.</p><ol><li>“The content is disjointed! No matter how much I read, I just don’t get it. I’m calling support.”</li></ol><p>Hmm …</p><p>Disjointed content cuts deeply. Getting this right is the squared-circle of geometry. The holy grail of documentation.</p><p>Luckily, it too can be solved geometrically.</p><h3>Circles, Squares, Triangles</h3><h4><strong>We don’t want circularity.</strong></h4><p>Circularity means readers are going in circles looking for answers. Sometimes the text contradicts itself, or repeats itself without ever making sense, or links back to the same page — over and over and over again, the very same sentence, with no way out, back to the beginning, we don’t want circularity, …</p><p>How do we help the reader break out of that circle? We don’t write in circles…</p><h4><strong>What about the square?</strong></h4><p>Surely, if our documentation covers the “four corners” of a subject, we’ve done our job as technical writers. We’ve created an overview, tutorials, examples, and a formal reference page. We’ve got the perfect square — a self-contained, perfectly organized website, with all the right content.</p><p>But maybe not. I would worry, at this point, if our square hasn’t made us complacent. I’ve seen a lot of good documentation out there, many of it perfectly clear and organized <em>and</em> not successful. Its readers are either frantically looking for information and not finding it, or they are not reading anymore. Instead, they are googling, hacking, and calling support.</p><p>And they are building far less of our software — going below and beneath what our software is capable of offering. Because it takes too much effort. The math is too great. It’s not worth going any further.</p><h4><strong>Building software with triangles</strong></h4><p>The triangle is a powerful architectural shape. It forms the structural basis of all buildings and bridges. And it is not about architectural <em>drawing</em>: The triangle is a physical reality — structures are built using physical matter in triangular shapes.</p><p>For the technical writer-turned-geometer, a triangle is a two-dimensional way to think about his or her craft. Already we have the sentence, paragraph, and page — the three sides of a triangle. As such, the triangle is a microcosm of the whole — we can use these triangles to <em>start</em> building an understanding of the software. <em>Start</em>, I repeat.</p><p>Documentation builds software, and the triangle is about building. There are two ideas behind this:</p><ol><li>A page is merely one triangle among many.</li><li>Many triangles are needed to build something solid.</li></ol><p>These two statements should push us out of our comfort zone and force us to think more globally about what we and our readers are trying to build together.</p><h4>Maps — Then greatest of the two-dimensional</h4><p>Do we really write in only two dimensions? Do we need more? If we think of <strong>maps</strong> — street maps, elevations, land usage, populations, climates, and so on — all of which are essentially two-dimensional representations of the “real world”; if we think about how they combine to help orient and teach us, we can sincerely wonder whether we need anything else.</p><p>[Note to self: last sentence could use some horizontal love.]</p><p>So … if we think of <em>maps</em>, two dimensions seems to be enough.</p><p>Do we need to add a third and fourth dimension? We already have that, we <em>live</em> in it: three-dimensional space, with time-constraints, constitutes not only the world in which we live but the one in which we build software. To get from point A to B, a map is sufficient: we only need take out our folded map or smartphone’s GPS.</p><p>But has the map metaphor taken us to another kind of complacency? Have we forgotten the unanswered question above, about content being <em>disjointed</em>? How do we know where to go, and when. Where is the wisdom? What about the holy grail? <em>Where</em> is the holy grail?</p><h4>At the Intersection of its pages</h4><p>We are walking through a city. We step into its buildings and neighborhoods. And as we interact with its space, we build structures.</p><p>Surveyors use triangles to define space. Joined and overlapping triangles create location. With precision, these locations help us map out the world. Aligning and combining <em>multiple</em> maps creates a dimensionality that more or less resembles the real world. Flat, yes — but fully represented.</p><p>Each individual page in software documentation can be combined with one or more pages to create a <em>full</em> understanding of a <em>single </em>feature. Good technical documentation is ultimately a question of set theory: Software is not built at the individual page, but at the <em>intersection</em> of its pages. No one page is sufficient. What is required is that content be found easily, and that it can be combined to create the illusion of unity, to help developers build their unique universes.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4c152a92f64d" width="1" height="1" alt=""><hr><p><a href="https://medium.com/writers-blogk/software-documentation-is-geometry-4c152a92f64d">Writing only needs two dimensions</a> was originally published in <a href="https://medium.com/writers-blogk">Writer’s Blogk</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Technical Writers Blog Also]]></title>
            <link>https://medium.com/writers-blogk/technical-writers-blog-also-8cf86efd508c?source=rss----87cecf19207---4</link>
            <guid isPermaLink="false">https://medium.com/p/8cf86efd508c</guid>
            <category><![CDATA[blogging]]></category>
            <category><![CDATA[writer]]></category>
            <category><![CDATA[technical-writer]]></category>
            <category><![CDATA[technology]]></category>
            <dc:creator><![CDATA[Peter Villani]]></dc:creator>
            <pubDate>Fri, 08 Feb 2019 16:39:39 GMT</pubDate>
            <atom:updated>2019-03-29T10:00:22.643Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HEDTzrgPIDpgHMLLhdm_Gg.jpeg" /></figure><p>For some technical writers, writing a blog comes as a relief, a sudden respite from the exigencies of precision and concision. Like when a tour guide goes off alone onto the less-trodden paths of her homeland, plunging deeply into familiar digressions of ambiguity, subjectivity, and multiple levels of meaning. Technical writers can digress too. In a blog.</p><blockquote>The success of a blog lies not in its content but in what it provokes, because while everything on the surface is content, nothing being said is on the surface.</blockquote><p>Thus freed from helping others to understand precise technical terms or do something correctly, a blog attempts to help people think differently and to engage them to say not only Yes or No but Maybe. Writing a blog can move a reader from one vague point to another, because life is the stuff we place in suspension between two edges. Before falling …</p><blockquote>The blog takes its time because it needs space.</blockquote><p>A blog gives space for the technical writer to embellish and the reader to reflect. It’s an open flow, where the writer can guide the reader into the same space as herself, or can suggest to the reader to go somewhere else. It’s entirely up to each writer and reader to define.</p><p>The subtext in a blog can be more present than the text, the surface only an excuse to engage. The words of a blog are sometimes opposed to their plain meaning. The writer can write with one intention, while the reader takes away something entirely different.</p><blockquote>Developing an idea in a blog is far more important than completing it.</blockquote><p>A blog is a collection of more than one idea in parallel, where each idea is a thread that needs space to move within, a space that resides not only in the text but in the reader’s will to invent and behold.</p><p>A blog is not technical writing. Which is good for both blogging and technical writing. 😌</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8cf86efd508c" width="1" height="1" alt=""><hr><p><a href="https://medium.com/writers-blogk/technical-writers-blog-also-8cf86efd508c">Technical Writers Blog Also</a> was originally published in <a href="https://medium.com/writers-blogk">Writer’s Blogk</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Skimmabilty, or the Art of Technical Writing]]></title>
            <link>https://medium.com/writers-blogk/skimmabilty-or-the-art-of-technical-writing-d68995d5dfb0?source=rss----87cecf19207---4</link>
            <guid isPermaLink="false">https://medium.com/p/d68995d5dfb0</guid>
            <category><![CDATA[writing-tips]]></category>
            <category><![CDATA[technical-writing]]></category>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[technology]]></category>
            <category><![CDATA[writer]]></category>
            <dc:creator><![CDATA[Peter Villani]]></dc:creator>
            <pubDate>Fri, 08 Feb 2019 16:38:29 GMT</pubDate>
            <atom:updated>2019-03-07T11:56:15.325Z</atom:updated>
            <content:encoded><![CDATA[<h3>Skimmabilty in Technical Writing</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*PvN1PB2FED4JW1rB2rsPHA.jpeg" /></figure><p>While rethinking my company’s technical documentation, deciding on how to improve the developer experience, I had a revelation. I suddenly knew what developers needed from technical documentation.</p><blockquote>I know that revelations are not always true. In fact, they are sometimes so wrong that they are dangerous, making us believe we are in the presence of truth, getting us to act, take decisions, without encouraging us to put into question whether the force of the revelation is stronger than its truth.</blockquote><p>At most, “revelatory truth” is a circuit breaker. It is a sudden electrical force that lights up an entire sky and then explodes, burning away the dark, uncomfortable matter of confusion and unknowing.</p><p>Our bodies are deeply uncomfortable with not knowing, so we need a release, and revelation gives us just that — It gets us to exclaim: I’ve got it! Now I know! We feel freed and enlightened.</p><p>But turning a bright light onto a dark shadow only makes the shadow disappear, the object still exists, and it still needs to be discovered and examined.</p><p>But anyway, What was this revelation? And did it hold any grain of truth?</p><p>Here it is, in all its truth and falseness: <strong>Developers don’t read. They skim.</strong></p><p>At its worse, this revelation tells me that developers rely on an advanced form of skimming called scrolling, which they do at lightning speed until they find <em>code</em>, which they then copy, paste, and compile, and then spend the rest of their time resolving runtime errors — all this as opposed to, say, reading.</p><blockquote>Developers don’t read. Did I already say that? As a technical writer, I am forced to ask: What are my words producing? The answer: Thicket.</blockquote><p>I am not writing, I am creating thicket. Words, sentences, long paragraphs, pages of content — in a “word”, all non-code-content is essentially thicket to be bushwhacked to reach code.</p><p>Thicket or perfect text, it’s all the same: verbiage in the way of doing.</p><p>By the way, the revelation didn’t say “the less said, the better”. I’ve already had that one, and that wasn’t easy to digest either— What kind of writer likes to write less? But this one’s more existential — Don’t write. What kind of writer does not want to write? And yet in the perfect developer world, code + a few choice words should be sufficient.</p><blockquote>The revelation is that I need to create skimmable content. Skimmable is not even a word. But it’s easier to understand a single non-word like skimmable than to read 10 words like “content that one can understand on the spot without reading”.</blockquote><p>Well, the revelation does indeed ring true, and as I sort of rant about it, I convince myself of its truth — and then I nonetheless go back to work creating short, single-idea sentences, simple, short paragraphs, useful, short pages, and no code at all, but with clear links to pages with loads of code and examples, thus striking a compromise that satisfies my technical and increasingly non-technical readers who most definitely read, because many of them are not there to code but to understand, analyze, use (not code), decide, manage, buy, and/or understand what their developers are doing. (Still reading? That run-on just kinda slipped out.)</p><p>And then I get the job done, wait for feedback, and its mostly positive, even from the developers who appreciated that I had taken the time to explain the concepts behind the code.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d68995d5dfb0" width="1" height="1" alt=""><hr><p><a href="https://medium.com/writers-blogk/skimmabilty-or-the-art-of-technical-writing-d68995d5dfb0">Skimmabilty, or the Art of Technical Writing</a> was originally published in <a href="https://medium.com/writers-blogk">Writer’s Blogk</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>