<?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[Stories by Peter Villani on Medium]]></title>
        <description><![CDATA[Stories by Peter Villani on Medium]]></description>
        <link>https://medium.com/@codeharmonics?source=rss-8c5dc6c37ebf------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/2*-VNZrSDlxvjPKfR1AgxI5g.jpeg</url>
            <title>Stories by Peter Villani on Medium</title>
            <link>https://medium.com/@codeharmonics?source=rss-8c5dc6c37ebf------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 22:54:51 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@codeharmonics/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Third-person narrator. The fly on the wall is not omniscient.]]></title>
            <link>https://medium.com/@codeharmonics/third-person-narrator-god-vs-the-fly-on-the-wall-f5d3ab31285c?source=rss-8c5dc6c37ebf------2</link>
            <guid isPermaLink="false">https://medium.com/p/f5d3ab31285c</guid>
            <category><![CDATA[novel]]></category>
            <category><![CDATA[writing-tips]]></category>
            <category><![CDATA[storytelling]]></category>
            <dc:creator><![CDATA[Peter Villani]]></dc:creator>
            <pubDate>Wed, 29 Jun 2022 19:59:07 GMT</pubDate>
            <atom:updated>2022-06-29T20:04:53.290Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*iLA8ZeM7EFRP5PkXw9OpAg.jpeg" /><figcaption>Photo by Egor Kamelev: <a href="https://www.pexels.com/photo/two-green-beetles-on-leaf-1114313/">https://www.pexels.com/photo/two-green-beetles-on-leaf-1114313/</a></figcaption></figure><h4>I love my fly on the wall almost as much as I love my characters. But I also own a fly swatter. Understanding the third-person narrator.</h4><p>As a narrator, a fly on the wall is not God. God knows everything — every thought, feeling, observation, judgment, opinion, and action of every character. God knows who the characters are, where they come from, and what will happen to them. God knows every scene before they occur. God knows the whole story — beginning, middle, and end. God controls everything, including the author. God might even <em>be</em> the author — creating the whole novel as if it were not real.</p><p>A fly is different from God — otherwise, religion would be even more tragic than it already is. A fly is simply a storyteller. Its job is to tell a story <em>as it unfolds.</em></p><h4>Why I love my fly</h4><p>The fly can see and describe a whole scene, but only as it unfolds in time. It can also enter inside the heads of different characters, reporting on their actions, thoughts, needs, observations, and judgments. But this doesn’t mean the fly knows the whole story to the end, or all the motives and thoughts of the characters: it’s simply seeing and reporting on events <em>as they unfold. </em>And it’s choosing only the most significant events, to tell the best story.</p><p>The fly is a well-positioned and agile storyteller. It has the whole space of the functional world in which to fly around. It doesn’t have to remain on the wall, it can fly near the characters, or out of the room where there are no characters. It can fly into their past, and collect information.</p><p>The fly has a keen and intuitive sense of observation. It’s sensitive to the characters, but the prose remains (generally speaking) <em>neutral</em>. In terms of <em>point of view,</em> it tells the story from the point of view of a non-participating/invisible <em>storyteller</em>.</p><p>But the fly, being curious in getting to the bottom of the whole story, also relies on what the characters are thinking and feeling.</p><p>With all this collected information, the fly can report back to the reader. The fly is therefore the<em> first</em> reader of the unfolding actions in the novel, and it becomes the only means for all other readers to learn about the events that have taken place. It uses drama to retell the story.</p><p>Thus, God is a fully unrestricted narrator and the fly has varying degrees of restrictions on what it knows about, what it can see, or how much it judges the characters. A fly, therefore, has more variety than God. It can be detached from the story, or more or less attached. It can be friendly to the characters, or annoying and judgemental.</p><p>Some flies like to be lyrical, considering themselves authors, with poetic prose and great insights. These flies like to draw attention to themselves. Other flies pride themselves on being invisible.</p><p>There’s the pet or mascot fly, who truly represents one or more of the characters. It’s loyal and has only the interests of the character or characters in mind.</p><p>There’s the fly caught in the glass bottle unable to fly away, so it can only tell us what it sees from that position. This fly is quite common. We feel its claustrophobia.</p><h4>The fly swatter</h4><p>And there’s the fly-swatter. That relationship between fly and character, where the fly is free to tell its story unless one of the characters swats the fly out of the narrative space. The fly, in this scenario, may come back unnerved to try to take back control, only to be swatted again.</p><p>More can be said about the fly swatter. Probably a whole novel. Where the true battle is not between God and the author, but between the author and its characters.</p><h4>With God and the Fly gone, we have close third-person narrative</h4><p>And finally — What happens when God and the fly are gone? Who tells us the story? This is where the participants in the story must take over and tell their own story.</p><h4>Ok, what about my novel?</h4><p>I have chosen to use only one narrative voice throughout my novel. I’ve called it the friendly fly. It’s a <em>fly</em>, because it sits on the wall and cares about my characters. And it can also fly freely anywhere in my novel and tell us what it sees, including the actions and thoughts of my beloved characters. It’s <em>friendly,</em> because it leaves the characters enough space to express themselves in their own terms. And it’s friendly to my story: it’s a good listener.</p><p>I have two main characters. The fly has a different friendship with each.</p><p>The fly hovers over Daniel as Daniel tells us what he sees and thinks. The fly will sometimes add insights and will also edit Daniel’s words to make them more interesting or literary. The fly essentially lets us see the story as Daniel sees it, but it sheds light on things Daniel might not see, or waxes eloquent to create suspense.</p><p>When Frank takes center stage, the same fly must now adapt to a more conflictual relationship. Frank owns a fly-swatter. So the fly has to compete for space with Frank. Sometimes, Frank just won’t let the fly say anything. Other times, Frank controls what the fly says. And in rare moments, the two speak simultaneously.</p><p>These two narrations create a consistent tone throughout, except for Frank’s loud voice, which breaks the narration. Daniel and the fly become the main <em>storytellers</em> and Frank becomes the main <em>character</em>. The conflictual relationship Frank has with Daniel and the fly helps show the overall conflictual relationship Frank has with everything.</p><p>As I might have mentioned at the start: I love my fly almost as much as my characters. But to be true, I too own a fly swatter.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f5d3ab31285c" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <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-8c5dc6c37ebf------2</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>Sun, 07 Apr 2019 07:23:41 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-8c5dc6c37ebf------2</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 11:37:07 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-8c5dc6c37ebf------2</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:18 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[Blogging to Overcome Technical Writer’s Block]]></title>
            <link>https://medium.com/technical-writing-is-easy/blogging-to-overcome-technical-writers-block-47945eedf227?source=rss-8c5dc6c37ebf------2</link>
            <guid isPermaLink="false">https://medium.com/p/47945eedf227</guid>
            <category><![CDATA[writer]]></category>
            <category><![CDATA[blogging]]></category>
            <category><![CDATA[writers-block]]></category>
            <category><![CDATA[technical-writer]]></category>
            <category><![CDATA[technology]]></category>
            <dc:creator><![CDATA[Peter Villani]]></dc:creator>
            <pubDate>Sat, 09 Feb 2019 20:27:09 GMT</pubDate>
            <atom:updated>2019-10-21T12:02:04.588Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0py30GtDHC_rHNPQmuDEfQ.png" /></figure><blockquote>This is the last in a series of articles in which I express frustration with the art of technical writing. This series came about while undertaking a particularly difficult assignment for my company. Writer’s block can be selective — it was far easier to blog than to do my assignment. But it’s thanks to blogging that I finally faced the beastly assignment.</blockquote><p>Our day jobs are punctuated with the purely executory, like filling out papers and filing folders, or performing hundreds of simple hand / eye movements to complete a daily or weekly chore.</p><p>Some jobs are <em>only</em> this, and I am thankful that this is not my case, as technical writer. However, <em>as</em> technical writer, I am hounded by the mundane and repetitive task. I avoid thinking about the number of times I’ve renamed files and folders, redirected URLs, cleaned up code, added or deprecated parameters, shortened already short half-sentences, and searched and replaced one boring technical term with another.</p><p>Basically, a lot of what a technical writer does is a form of punishment for having created a monstrous tome of esoteric reference material called documentation.</p><p>But every job has its pitfalls. So what’s different about technical writing? What’s the darker side?</p><p>Before getting dark, let me say something bright. When I am given a blank sheet of paper, and a rich subject on which to write, and <em>carte blanche</em> to do what I do best, which is to “break down complex information into an understandable form”, then there’s no stopping me. Time stands still, deadlines come and go, a writer is writing. Ecstasy comes to mind.</p><p>Unfortunately, I am not often given <em>carte blanch</em>. My <em>carte </em>turns <em>rouge</em> — red like blood. Deadlines do not come and go, they stay.</p><p>So let’s not delay — What’s the real evil in being a technical writer?</p><p>Consider a large writing task, one that will be scrutinized and reviewed by people who do not share your vision of technical documentation. Or maybe you do not share their focus on helping developers do their job. You’re more interested in engaging the reader, expanding her universe.</p><p>The people who review my work are highly competent and driven people. They are - to a fault - highly technical insiders who know more about the subject than their readers do, and who think they know more about technical writing than me. But maybe I confuse <a href="https://medium.com/technical-writing-is-easy/to-document-to-write-8096325bf6a6"><em>writing</em> with <em>technical writing</em></a>, and I resist what they are saying and they resist what I am saying, and so we are blocked, or more to the point, I am blocked, writery blocked.</p><p>Ok, so in plain language, what am I complaining about? The difficulty I have with technical writing is that I can’t do it in the proper way. We have a review process. We have several layers of review. Nobody in the review process is a writer. Everybody is technical. The point of the review is to ensure that what I write is useful to technical people. But who is my audience? I think the insiders forget that we write for outsiders, people with different purposes, technical abilities, points of view, and learning styles. I have to write <a href="https://medium.com/writers-blogk/skimmabilty-or-the-art-of-technical-writing-d68995d5dfb0">texts that work for everybody</a>.</p><p>But it’s an uphill battle to prove that bullet points are not always preferable, or that immediate access to raw facts and code is not always meaningful for people who need more context. It’s an uphill battle that tires me, my legs give out at the start of each ascent, with each new assignment. I find myself hesitating, not wanting to face the next challenge. I get stuck. I don’t move. The uphill does not change. A large block, like a monolith, crushes, blocks my path. Technical writer’s block.</p><p>But all writing is a dark undertaking. There is always scrutiny. There is always another way to write that differs from an editor’s preferences.</p><p>What makes technical writing a particularly dark challenge, though, is that the scrutiny is not about voice or story, or the beautiful ambiguity of words, but on the accuracy of the facts and the conciseness of their expression. These days we speak about voice and tone in technical documentation, which is a relief and a really good move forward, but these terms are often overly formalized or formulaic, acceptable if upbeat and friendly, carefully idiomatic and fun, but never ironic or provocative or reflective or lengthy, lengthy, and (did I say?) lengthy without much of a point …</p><p>Well, now I need to get back to work.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=47945eedf227" width="1" height="1" alt=""><hr><p><a href="https://medium.com/technical-writing-is-easy/blogging-to-overcome-technical-writers-block-47945eedf227">Blogging to Overcome Technical Writer’s Block</a> was originally published in <a href="https://medium.com/technical-writing-is-easy">Technical Writing is Easy</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-8c5dc6c37ebf------2</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>Tue, 05 Feb 2019 12:34:33 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[To Document, To Write]]></title>
            <link>https://medium.com/technical-writing-is-easy/to-document-to-write-8096325bf6a6?source=rss-8c5dc6c37ebf------2</link>
            <guid isPermaLink="false">https://medium.com/p/8096325bf6a6</guid>
            <category><![CDATA[technical-writer]]></category>
            <category><![CDATA[technology]]></category>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[writer]]></category>
            <dc:creator><![CDATA[Peter Villani]]></dc:creator>
            <pubDate>Fri, 25 Jan 2019 23:23:36 GMT</pubDate>
            <atom:updated>2019-03-13T16:04:19.089Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*E4rMivDDauz8sM-KiJuCEA.jpeg" /></figure><p>When I am asked to define my role, I start with “Technical Writers write Technical Documentation”. But to be honest, the word in the middle is incorrect: there’s a difference between <em>writing </em>and <em>documenting.</em></p><p>For example:</p><ul><li>We <em>document</em> API methods and parameters, filling pages with code, syntax, and expected data formats and types. Facts.</li><li>We <em>write</em> technical guides, making difficult concepts easily understood, help users follow best practices, enlighten.</li></ul><p>The difference is therefore pretty straightforward.</p><h4>To Document</h4><blockquote>API documentation requires as little wording (i.e., writing) as possible. It is thorough, precise, a source of truth. Mistakes are intolerable.</blockquote><p>The pages of good API documentation should contain mostly code and one-word descriptions like “boolean” or “optional”. The key ingredient is <em>useful: </em>they should be immediately useful and not get anyone to think. Tell not show, and definitely not entertain. They should get people up and running, fast.</p><p>It is different for guides.</p><h4>To Write</h4><p>It is different for guides.</p><blockquote>Time slows down in the guides. For one, they require more words, more writing. They verbally walk people through concepts.</blockquote><p>Guides make arguments, describe benefits, carefully discuss costs and benefits, alert readers to dangers, and make recommendations, encourage must-dos, and clarify what not to do. And no code allowed.</p><p>The experience is transformative. Users becomes readers. The reader goes from impatient hacker to informed coder to master developer. Better coding. Better implementation. Less errors. More advanced features.</p><h4>Still more about writing</h4><p>The benefit of well-<em>written</em> guides? The API provider is happy because its customers have more confidence. Customers are happy because the API product is kick-ass and well-implemented and easy to maintain. And the API support team is relieved that their slack channels and forum discussions are not ringing off the hook.</p><p>And the writer, well … <a href="https://medium.com/@codeharmonics/skimmabilty-or-the-art-of-technical-writing-d68995d5dfb0">is he or she or they happy</a>?</p><h3>Technical writing is not writing</h3><p>I come from both a technical and writing background. Technical in that I was once a developer. Writing in that I loved writing as a creative and personal extension of myself. As for my technical writing background, I documented code and wrote technical and functional specifications.</p><p>I therefore documented and wrote. The difference was clear. When my audience had time to read, I had the opportunity to write longer sentences and more content.</p><blockquote>Now, I am writing for large numbers of developers, over 10s of thousands, all of whom I will never meet except maybe on the streets of my big city, without knowing it. With this kind of anonymity, I am forced to make a compromise. I am forced to follow the model of documenting.</blockquote><p>This means: keeping things simple, getting straight to the point, and adding no embellishments or metaphor, just facts. To minimize words, to speak in code, not computer code, but in a coded simplified language that helps developers find and digest information easily.</p><p>Not knowing your readers means not using words that will be misunderstood, so best to use as little words as possible. <a href="https://medium.com/@codeharmonics/skimmabilty-or-the-art-of-technical-writing-d68995d5dfb0">To write less</a>.</p><h3>Good technical documentation should be conversational</h3><p>So they say. But in fact, the conversation is always the same: this is X, X means Y, and you need to use X to do Z. And there’s only so many variations on this formula, and why vary it? If it works, do it all of the time.</p><h3>On the nature of truth in guides , or using metaphors in documentation</h3><p>Okay, one more point. Or, where do I put this paragraph:</p><p>Some guides use metaphors. Metaphor is, for me, clearly on the writing side of the documentation/writing divide.</p><p>Is a metaphor true? This is a good question for a technical writer to ask in deciding whether or not to use a metaphor. The best answer is yes and no. A metaphor uses a somewhat true scenario as an analogy to guide the reader through a difficult concept. The analogy is usually only half true — that is, only half of it applies. The goal, however, is to get the reader to start thinking about the idea or concept in a way that seems familiar, and to use that familiarity as a metaphorical bridge to unfamiliar territory. The hope is that when they code, they’ll know what they are doing and why.</p><p><a href="https://medium.com/@codeharmonics/software-documentation-is-geometry-4c152a92f64d">Writing is that bridge</a>. But I’m not sure we need that bridge anymore.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8096325bf6a6" width="1" height="1" alt=""><hr><p><a href="https://medium.com/technical-writing-is-easy/to-document-to-write-8096325bf6a6">To Document, To Write</a> was originally published in <a href="https://medium.com/technical-writing-is-easy">Technical Writing is Easy</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-8c5dc6c37ebf------2</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>Sun, 20 Jan 2019 17:19:33 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>
        <item>
            <title><![CDATA[Exploring (API Documentation) Space]]></title>
            <link>https://medium.com/@codeharmonics/exploring-api-documentation-space-b53be5a4fafc?source=rss-8c5dc6c37ebf------2</link>
            <guid isPermaLink="false">https://medium.com/p/b53be5a4fafc</guid>
            <category><![CDATA[api-documentation]]></category>
            <category><![CDATA[space-exploration]]></category>
            <category><![CDATA[writing]]></category>
            <category><![CDATA[search-engines]]></category>
            <category><![CDATA[documentation]]></category>
            <dc:creator><![CDATA[Peter Villani]]></dc:creator>
            <pubDate>Wed, 11 Oct 2017 07:31:56 GMT</pubDate>
            <atom:updated>2019-04-26T19:41:08.096Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3f0iF5a82i3xyEaX7og65w.jpeg" /><figcaption>That’s me traveling in the documentation space</figcaption></figure><p>Awe. Like I am part of something insanely large. Touching infinity.</p><p>We travel in space. We are <em>in</em> space, and we and everything in it are moving.</p><p>To see this, get out of the city and into the dark country. Lay back on the ground and face the sky.</p><p>It takes about 30 minutes for your eyes to adapt.</p><p>And then feel the movement.</p><p>This is what happens after a few days at Algolia. You take a step back, and you see something rare, extraordinary — an insanely large and infinite potential.</p><p>The stars are within reach. They are in the open space, and in the super quiet, with genuine conversation in the hallways, kitchen, and on the couches. We are all traveling together.</p><p>I write and rewrite technical content — I help get the message out about how to use Algolia software.</p><p>I chart the stars, imagining the constellations of the Algolia universe. Exploring space — gathering all of the information we have — technical documents, white papers, support tickets, and other written <em>morceaux</em> — even blogs and videos and recordings of conferences and webinars — and putting all of this within reach of our customers — on a single platform —</p><p>in a way that makes sense —</p><p>but retains the wonder, the infinite potential.</p><p>I’d like to say that I know the names of every star and constellation. But in fact, I don’t any of them. I often close my iPhone App, the one that gives me all of the names of the stars, and instead I just look up and let my imagination inform me. What we do at Algolia is provide a Search engine, which is not very from from space exploration.</p><p>I am not yet sure how Search applies to what I am attempting to do with our technical documentation — but to give our developer-customers the feeling of being <em>connected</em>, by adding an Algolia Search experience within its own documentation universe, will play a significant role.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b53be5a4fafc" width="1" height="1" alt="">]]></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-8c5dc6c37ebf------2</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>Mon, 02 Oct 2017 21:32:03 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>
    </channel>
</rss>