davidbgk
/
larlet-fr-david-cache

<!doctype html><!-- This is a valid HTML5 document. -->
<!-- Screen readers, SEO, extensions and so on. -->
<html lang="fr">
<!-- Has to be within the first 1024 bytes, hence before the `title` element
  See: https://www.w3.org/TR/2012/CR-html5-20121217/document-metadata.html#charset -->
<meta charset="utf-8">
<!-- Why no `X-UA-Compatible` meta: https://stackoverflow.com/a/6771584 -->
<!-- The viewport meta is quite crowded and we are responsible for that.
  See: https://codepen.io/tigt/post/meta-viewport-for-2015 -->
<meta name="viewport" content="width=device-width,initial-scale=1">
<!-- Required to make a valid HTML5 document. -->
<title>Writing Is Magic (archive) — David Larlet</title>
<meta name="description" content="Publication mise en cache pour en conserver une trace.">
<!-- That good ol' feed, subscribe :). -->
<link rel="alternate" type="application/atom+xml" title="Feed" href="/david/log/">
<!-- Generated from https://realfavicongenerator.net/ such a mess. -->
<link rel="apple-touch-icon" sizes="180x180" href="/static/david/icons2/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/static/david/icons2/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/static/david/icons2/favicon-16x16.png">
<link rel="manifest" href="/static/david/icons2/site.webmanifest">
<link rel="mask-icon" href="/static/david/icons2/safari-pinned-tab.svg" color="#07486c">
<link rel="shortcut icon" href="/static/david/icons2/favicon.ico">
<meta name="msapplication-TileColor" content="#f7f7f7">
<meta name="msapplication-config" content="/static/david/icons2/browserconfig.xml">
<meta name="theme-color" content="#f7f7f7" media="(prefers-color-scheme: light)">
<meta name="theme-color" content="#272727" media="(prefers-color-scheme: dark)">
<!-- Documented, feel free to shoot an email. -->
<link rel="stylesheet" href="/static/david/css/style_2021-01-20.css">
<!-- See https://www.zachleat.com/web/comprehensive-webfonts/ for the trade-off. -->
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_regular.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin>
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_bold.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin>
<link rel="preload" href="/static/david/css/fonts/triplicate_t4_poly_italic.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" crossorigin>
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_regular.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin>
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_bold.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin>
<link rel="preload" href="/static/david/css/fonts/triplicate_t3_italic.woff2" as="font" type="font/woff2" media="(prefers-color-scheme: dark)" crossorigin>
<script>
    function toggleTheme(themeName) {
        document.documentElement.classList.toggle(
            'forced-dark',
            themeName === 'dark'
        )
        document.documentElement.classList.toggle(
            'forced-light',
            themeName === 'light'
        )
    }
    const selectedTheme = localStorage.getItem('theme')
    if (selectedTheme !== 'undefined') {
        toggleTheme(selectedTheme)
    }
</script>

  <meta name="robots" content="noindex, nofollow">
  <meta content="origin-when-cross-origin" name="referrer">
  <!-- Canonical URL for SEO purposes -->
  <link rel="canonical" href="https://brooker.co.za/blog/2022/11/08/writing.html">

<body class="remarkdown h1-underline h2-underline h3-underline em-underscore hr-center ul-star pre-tick" data-instant-intensity="viewport-all">


<article>
  <header>
    <h1>Writing Is Magic</h1>
  </header>
  <nav>
    <p class="center">
      <a href="/david/" title="Aller à l’accueil"><svg class="icon icon-home">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-home"></use>
      </svg> Accueil</a> •
      <a href="https://brooker.co.za/blog/2022/11/08/writing.html" title="Lien vers le contenu original">Source originale</a>
    </p>
  </nav>
  <hr>
  <p class="meta">Magic can be dangerous.</p>

<p><em>Sometimes when folks ask me for advice at work, I write them very long emails to answer their question. Sometimes, those emails are generally interesting and not work-specific, so I share them here. A couple days ago somebody asked me about how to get better at communicating their ideas and opinions, how to extend their influence, and how to drive consensus. This was my reply.</em></p>

<p>There are many ways to be influential. You can form 1:1 relationships with people, have small group meetings, do talks, send out a code review, or argue in Slack. All of those can be valuable at the right time. But there's one tool that I choose most often: long-form writing. Writing is the closest thing I know to magic.</p>

<p>Nearly every time I need to drive a difficult, subtle, or contentious decision, I write a document. Sometimes that's half a page, sometimes its six pages. Sometimes much longer, although brevity is valuable. I see a few benefits to this approach that keep me coming back it it again and again.</p>

<p>First, clarity. I'm sure you know the quote "Writing is nature’s way of letting you know how sloppy your thinking is"<sup><a href="#foot1">1</a></sup>, and knowing how sloppy your thinking is allows you to sharpen it, test your arguments, and test different explanations. I find, more often than not, that I understand something much less well when I sit down to write about it than when I'm thinking about it in the shower. In fact, I find that I change my own mind on things a lot when I try write them down. It really is a powerful tool for finding clarity in your own mind. Once you have clarity in your own mind, you're much more able to explain it to others.</p>

<p>Second, time. Getting people's full, focused, attention on your ideas is very hard. Reading, if your team has a strong document culture, is one of the only ways to do that. You give people a couple pages to read, ideally on paper, and they're likely to be quiet and focus on understanding your ideas for at least a few minutes. You get to be there, in their heads, with nothing else, for a while. You get to lay out an argument, tell a story, present some data, or ask their opinion without interruption, without back-and-forth. Just your voice. There are very few other ways to do that.</p>

<p>Third, scale. Sometimes documents only live for an hour or so. They're there to drive a decision, and when the decision is made the document is dead. Much more often, in my experience, they live well beyond the initial reading. I've had people ask me questions about documents I wrote more than a decade ago, that they're still finding useful today. I love reading CS papers from before I was born. Writing scales in time much better than speaking. I also encourage people to share documents. They can go from the initial audience, to a whole team, to other stakeholders, to people working on similar problems. Writing scales in space much better than nearly any other way of communicating. Sometimes your writing may scale more than you want it to, in either time our space. You do need to watch out for that.</p>

<p>Fourth, authority. For some reason, people tend to believe the things I write more strongly than the things I say. Maybe its the fact I took the time I write suggests its worth their time to read. I've found many times that I've said the same thing over and over and over, and then once I write it down suddenly its The Law. You need to be super careful with that effect, if you see it yourself. It can stifle discussion and communication. It can lead to people treating your words as more certain than they really are, of turning your musings into dogma<sup><a href="#foot2">2</a></sup>. Sometimes it doesn't work at all, and you'll write something down to no effect, but I don't see that very often.</p>

<p>Finally, memory. I don't know if my memory is uniquely terrible, but I really do tend to forget things. I vividly remember the tuck shop menu from my primary school, 30 years ago. I don't always remember my justification for decisions I was pushing for last week. Writing is my own record. My own way to go back and see what I was thinking then, and whether its still true. Sometimes I find that I was much smarter two weeks ago than I am now. Sometimes its the opposite. Either way, the record is something I find valuable.</p>

<p>Writing takes time. Writing well takes a lot of time. On the other hand, the output of writing is almost always more clarity, and sometimes a clear decision. Over my career, I think I've wasted at least ten times more time going around and around in conversations without finding consensus than I have writing documents that didn't turn out to be valuable. It's very seldom that I think back over writing something and conclude that it wasn't a good investment of my time. That can happen, and you have to watch for it, but it doesn't happen to me a lot.</p>

<p>My last point is about reading culture. Sitting down to read, really read for understanding, is a learned skill. It's something I recommend that everybody practice, and model in their organizations. I like to discourage people from arguing in document comments. I especially discourage people from nitpicking. Seeking feedback <em>on the document</em> rather than <em>on the ideas in the document</em> is, of course, useful if you want to get better at writing. But it's way easier for a reader to nitpick grammar than it is to engage with ideas, so I like to time box that kind of feedback or take it to a different channel.</p>

<p>This isn't a complete answer to your question, but a partial one. Write more.</p>

<p><strong>Footnotes</strong></p>

<ol>
<li><a name="foot1"></a> Lamport <a href="https://dl.acm.org/doi/pdf/10.1145/2736348">attributes this</a> to <a href="https://en.wikipedia.org/wiki/Dick_Guindon">Dick Guindon</a>, but there are other credible attributions out there. No matter who said it first, it seems true.</li>
<li><a name="foot2"></a> Lev Grossman's Magicians series has this ongoing theme about how dangerous magic is to the people to practice it, and a lot of the difficulty isn't in harnessing power, its in having that power not destroy you when you do. I think about that a lot. Influence is something worth becoming great at, and I really admire some of the people who are the best at it, but you need to be really careful.</li>
</ol>
</article>


<hr>

<footer>
  <p>
    <a href="/david/" title="Aller à l’accueil"><svg class="icon icon-home">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-home"></use>
      </svg> Accueil</a> •
    <a href="/david/log/" title="Accès au flux RSS"><svg class="icon icon-rss2">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-rss2"></use>
      </svg> Suivre</a> •
    <a href="http://larlet.com" title="Go to my English profile" data-instant><svg class="icon icon-user-tie">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-user-tie"></use>
      </svg> Pro</a> •
    <a href="mailto:david%40larlet.fr" title="Envoyer un courriel"><svg class="icon icon-mail">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-mail"></use>
      </svg> Email</a> •
    <abbr class="nowrap" title="Hébergeur : Alwaysdata, 62 rue Tiquetonne 75002 Paris, +33184162340"><svg class="icon icon-hammer2">
        <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-hammer2"></use>
      </svg> Légal</abbr>
  </p>
  <template id="theme-selector">
      <form>
          <fieldset>
              <legend><svg class="icon icon-brightness-contrast">
                <use xlink:href="/static/david/icons2/symbol-defs-2021-12.svg#icon-brightness-contrast"></use>
              </svg> Thème</legend>
              <label>
                  <input type="radio" value="auto" name="chosen-color-scheme" checked> Auto
              </label>
              <label>
                  <input type="radio" value="dark" name="chosen-color-scheme"> Foncé
              </label>
              <label>
                  <input type="radio" value="light" name="chosen-color-scheme"> Clair
              </label>
          </fieldset>
      </form>
  </template>
</footer>
<script src="/static/david/js/instantpage-5.1.0.min.js" type="module"></script>
<script>
    function loadThemeForm(templateName) {
        const themeSelectorTemplate = document.querySelector(templateName)
        const form = themeSelectorTemplate.content.firstElementChild
        themeSelectorTemplate.replaceWith(form)

        form.addEventListener('change', (e) => {
            const chosenColorScheme = e.target.value
            localStorage.setItem('theme', chosenColorScheme)
            toggleTheme(chosenColorScheme)
        })

        const selectedTheme = localStorage.getItem('theme')
        if (selectedTheme && selectedTheme !== 'undefined') {
            form.querySelector(`[value="${selectedTheme}"]`).checked = true
        }
    }

    const prefersColorSchemeDark = '(prefers-color-scheme: dark)'
    window.addEventListener('load', () => {
        let hasDarkRules = false
        for (const styleSheet of Array.from(document.styleSheets)) {
            let mediaRules = []
            for (const cssRule of styleSheet.cssRules) {
                if (cssRule.type !== CSSRule.MEDIA_RULE) {
                    continue
                }
                // WARNING: Safari does not have/supports `conditionText`.
                if (cssRule.conditionText) {
                    if (cssRule.conditionText !== prefersColorSchemeDark) {
                        continue
                    }
                } else {
                    if (cssRule.cssText.startsWith(prefersColorSchemeDark)) {
                        continue
                    }
                }
                mediaRules = mediaRules.concat(Array.from(cssRule.cssRules))
            }

            // WARNING: do not try to insert a Rule to a styleSheet you are
            // currently iterating on, otherwise the browser will be stuck
            // in a infinite loop…
            for (const mediaRule of mediaRules) {
                styleSheet.insertRule(mediaRule.cssText)
                hasDarkRules = true
            }
        }
        if (hasDarkRules) {
            loadThemeForm('#theme-selector')
        }
    })
</script>
</body>
</html>