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>Making world-class docs takes effort (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://daniel.haxx.se/blog/2021/09/04/making-world-class-docs-takes-effort/">

<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>Making world-class docs takes effort</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.svg#icon-home"></use>
      </svg> Accueil</a> •
      <a href="https://daniel.haxx.se/blog/2021/09/04/making-world-class-docs-takes-effort/" title="Lien vers le contenu original">Source originale</a>
    </p>
  </nav>
  <hr>
  <p>Here are six requirements that I have on a project for it to reach my gold approval for stellar docs. Then something about what I’ve done recently to further improve the docs for curl.</p>

<h2>Your docs belong in the code repository</h2>

<p>It needs to be next to the code so that authors and contributors can update/read the docs while working on the code or docs. Providing it in a separate repository or otherwise separated will undoubtedly lead to discrepancies sooner or later. Similar to how <em>all wikis are always wrong</em>.</p>

<h2>Your docs is not extracted from code</h2>

<p>Admit it. If you browse around you will realize that the best documented projects you find never provide that docs generated directly from code. Such generated docs can still provide value, but you will not reach gold level without more effort.</p>

<p>Separated docs encourage more writing and writing by people who are otherwise scared of touching the code or thinking that fixing spelling errors in the docs isn’t worth patching the code for. It also allows for other and better formatting on the docs.</p>

<h2>Your docs features examples</h2>

<p>Users always ask for (more) examples. You can never go wrong by providing examples. If your docs don’t have enough examples, you’re not doing the docs good enough yet.</p>

<h2>You document every API call you provide</h2>

<p>Fewer things make me sigh more than when I have to dig up the source code and from that try to figure out exactly how an external and publicly provided API works. Yet this still happens regularly even for libraries that have been released and maintained for decades.</p>

<p>In one fairly recent instance I reported such an omission in a popular library. It took them over two years to add it.</p>

<p>Long-living libraries should also provide information about from which versions certain functionality or options exist or can be expected to work or not work.</p>

<h2>Your docs is easily accessible and browsed</h2>

<p>Good docs means that we can <em>find</em> what we’re looking for and that the documentation flows and is easily read and understood. Ideally, even simple google searches for API details in your library should lead us to suitable entry points.</p>

<p>Preferably, the documentation should also be provided for proper off-line reading, meaning man pages or something similar that can be browsed when disconnected from the Internet.</p>

<h2>Your docs should be easy to contribute to</h2>

<p>The docs should be easy for contributors to help out with (independently from the code if desired). That also includes that they should be easy for contributors to build and render locally so that they can test and view their updates while working on them.</p>

<h2>Documentation in the curl project</h2>

<p>I want the documentation for curl and libcurl to be known, recognized and widely admitted to be world-class.</p>

<p>I want the curl documentation to be of a quality and content to make users not able to find competitors or similar projects with better docs.</p>

<p>Documentation in curl is not an after-thought. It is not a second-tier component. It is a crucial and important foundation that allows users to use, trust and rely on our products. We require that new changes or improved functionality are provided with the corresponding updated and accurate documentation.</p>

<p>We also try to verify and check the docs as much as possible with scanners , tests and tools.</p>

<h2>Non-stop iterating is key</h2>

<p>I maintain that our documentation is as good as it is today a lot thanks to us very rigidly sticking to our guiding principles: <em>compatibility</em> and <em>not breaking existing behavior</em>. Documentation we wrote decades ago is still valid. It gives us plenty of time to keep refining and polishing the documentation of a feature that doesn’t change. No documentation was perfect already at the first attempt, but after numerous iterations and improvements chances are it is better. Time is on our side. And we are never done, documentation can always be improved.</p>

<h2>I’m putting in the work</h2>

<p>A few days ago I talked documentation with someone and when doing so I thought about what guiding principles I think we should put on project documentation. What I’ve listed above basically.</p>

<p>In then dawned on me that the current man curl.1 man page is actually not featuring that many examples, in spite of it being <strong>3535</strong> lines long. I pondered a little bit on how best add some, and then dove in and extended our system that generates it from the hundreds of individual files that each describe a single command line option. They should of course all offer at least one example!</p>

<p>Having <strong>242</strong> command line options (as of right now, it will be more soon), that sudden idea that seemed simple enough turned into a quite gruesome work and I spent many hours walking over the options to make up examples. I also made sure that our build system now returns an error if there’s a command option without an example in the documentation! This way, we can be sure that also all future command line options will have examples in the man page.</p>

<p>This made the curl.1 man page grew with over 1200 lines!</p>

<h2>libcurl options too</h2>

<p>A few years ago I did a manual effort and made sure most man pages for libcurl options include examples, but I never made that into a test or anything so there’s nothing that forces us to stick to this.</p>

<p>Having started this journey, I decided now was the time to add that requirement to the scripts. I extended test case 1173, which already scans all man pages to verify some basic syntax, to also check that man pages for options feature an <code>EXAMPLE</code> section.</p>

<p>There are at this moment <strong>374</strong> stand-alone man pages for libcurl options. Only ten of them were detected to not feature good enough examples and it wasn’t very hard to fix this.</p>

<h2>Consistency is good</h2>

<p>Having just extended the man page checker, another idea came up.</p>

<p>I made the script also check that each man page features the correct set of sections, in the required order! I’m a true believer in consistency and that using the same set in the same order will make the docs easier to read and find information in, and checking for these things will make sure that all future additions will be forced stick to the same.</p>

<p>The mandatory sections for libcurl option man pages are right now, in this order:</p>

<div class="wp-block-syntaxhighlighter-code "><pre class="brush: plain; title: ; notranslate" title="">
NAME
SYNOPSIS
DESCRIPTION
PROTOCOLS
EXAMPLE
AVAILABILITY
RETURN VALUE
SEE ALSO
</pre></div>

<p>These man pages are allowed to have other sections as well, and they can be placed anywhere among  the mandatory ones, but the eight section headers that has to be there has to be in that order.</p>

<h2>Cross-references</h2>

<p>While at it, I also extended the man page scanner to check that all references in all curl man pages to libcurl options are verified to actually refer to existing options, to find typos. Ironically this extra check turned out finding exactly <strong>no</strong> such typos in the current <strong>463</strong> man pages!</p>

<h2>Future</h2>

<p>The outcome of the work I write about here will of course be merged asap and will be part of future releases and on the website.</p>

<p>We should keep thinking of more ways to improve the documentation and for more ways to verify and cross-reference things mentioned in the docs to increase its accuracy and detect typos.</p>

<p>If you find a problem, an inferior wording or just something you think we should improve in any curl documentation, <a href="https://github.com/curl/curl/issues/new/choose">file a bug</a> or a <a href="https://github.com/curl/curl/pulls">PR</a>! We also try to make this as easy as possible for users to do directly from the <a href="https://curl.se/">curl website</a> by providing bug-reporting direct links from the documentation pages.</p>

<h2>Updates</h2>

<p>I added the sixth “rule” days after the initial post after Willy Tarreau’s feedback.</p>
</article>


<hr>

<footer>
  <p>
    <a href="/david/" title="Aller à l’accueil"><svg class="icon icon-home">
        <use xlink:href="/static/david/icons2/symbol-defs.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.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.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.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.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.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>