www

My personal website(s)
Log | Files | Refs

documentation.html (5732B)


      1 <!DOCTYPE html>
      2 <html lang="en">
      3   <head>
      4     <!-- Sep 03, 2024 -->
      5     <meta charset="utf-8" />
      6     <meta name="viewport" content="width=device-width, initial-scale=1" />
      7     <title>Documentation</title>
      8     <meta name="author" content="Vincent Demeester" />
      9     <meta name="generator" content="Org Mode" />
     10     <link rel='icon' type='image/x-icon' href='./images/favicon.ico'/>
     11     <meta name='viewport' content='width=device-width, initial-scale=1'>
     12 <link rel='stylesheet' href='./css/2022.css' type='text/css'/>
     13 <link rel='stylesheet' href='./css/syntax.css' type='text/css'/>
     14 <link href='/index.xml' rel='alternate' type='application/rss+xml' title='Vincent Demeester' />
     15 </head>
     16 <body>
     17 <main id="content" class="content">
     18 <header>
     19 <h1 class="title">Documentation</h1>
     20 </header><section id="outline-container-Documentation" class="outline-2">
     21 <h2 id="Documentation">Documentation&#xa0;&#xa0;&#xa0;<span class="tag"><span class="docs">docs</span>&#xa0;<span class="_link">#link</span></span></h2>
     22 <div class="outline-text-2" id="text-Documentation">
     23 </div>
     24 <div id="outline-container-%5B%5Bhttps%3A%2F%2Fdocumentation.divio.com%2F%5D%5BDocumentation%20System%5D%5D" class="outline-3">
     25 <h3 id="%5B%5Bhttps%3A%2F%2Fdocumentation.divio.com%2F%5D%5BDocumentation%20System%5D%5D"><a href="https://documentation.divio.com/">Documentation System</a></h3>
     26 <div class="outline-text-3" id="text-%5B%5Bhttps%3A%2F%2Fdocumentation.divio.com%2F%5D%5BDocumentation%20System%5D%5D">
     27 <p>
     28 <span class="timestamp-wrapper"><span class="timestamp">[2021-10-15 Fri 17:27]</span></span>
     29 </p>
     30 
     31 <blockquote>
     32 <p>
     33 The Grand Unified Theory of Documentation
     34 — David Laing
     35 </p>
     36 
     37 <p>
     38 There is a secret that needs to be understood in order to write good software
     39 documentation: there isn’t one thing called documentation, there are four.
     40 </p>
     41 
     42 <p>
     43 They are: tutorials, how-to guides, technical reference and explanation. They represent
     44 four different purposes or functions, and require four different approaches to their
     45 creation. Understanding the implications of this will help improve most documentation -
     46 often immensely.
     47 </p>
     48 </blockquote>
     49 
     50 <p>
     51 This is a set of resources around how setup a system to document your software/product
     52 correctly. And there is <b>four</b> distinctive type of documentation (different style of writing):
     53 </p>
     54 
     55 <ul class="org-ul">
     56 <li>Tutorials — <i>learning-oriented</i>
     57 Usually the most important to &ldquo;get-in&rdquo;, and usually not very well done.</li>
     58 <li>How-to Guides — <i>problem-oriented</i>
     59 Series of step required to solve a real-world problem.</li>
     60 <li>Explanation — <i>understanding-oriented</i></li>
     61 <li>References — <i>information-oriented</i></li>
     62 </ul>
     63 
     64 
     65 <figure id="org50fc4a9">
     66 <img src="./images/documentation/overview.png" alt="overview.png">
     67 
     68 </figure>
     69 
     70 <p>
     71 Given how wide is this set of pages, I might link several sub-entries here.
     72 </p>
     73 
     74 <p>
     75 <a href="https://www.youtube.com/watch?v=t4vKPhjcMZg">What nobody tells you about documentation</a> is the video from the author(s) of this set of pages.
     76 </p>
     77 </div>
     78 </div>
     79 <div id="outline-container-%5B%5Bhttps%3A%2F%2F8thlight.com%2Fblog%2Fmartin-gaston%2F2019%2F10%2F22%2Ftips-for-technical-writing.html%5D%5BTips%20for%20Technical%20Writing%20%7C%208th%20Light%5D%5D" class="outline-3">
     80 <h3 id="%5B%5Bhttps%3A%2F%2F8thlight.com%2Fblog%2Fmartin-gaston%2F2019%2F10%2F22%2Ftips-for-technical-writing.html%5D%5BTips%20for%20Technical%20Writing%20%7C%208th%20Light%5D%5D"><a href="https://8thlight.com/blog/martin-gaston/2019/10/22/tips-for-technical-writing.html">Tips for Technical Writing | 8th Light</a></h3>
     81 <div class="outline-text-3" id="text-%5B%5Bhttps%3A%2F%2F8thlight.com%2Fblog%2Fmartin-gaston%2F2019%2F10%2F22%2Ftips-for-technical-writing.html%5D%5BTips%20for%20Technical%20Writing%20%7C%208th%20Light%5D%5D">
     82 <p>
     83 <span class="timestamp-wrapper"><span class="timestamp">[2019-10-28 Mon 08:21]</span></span>
     84 </p>
     85 
     86 <blockquote>
     87 <p>
     88 Do you struggle to write blog posts? Developing your craft when it comes to writing can be
     89 as intimidating as the buggiest code.
     90 </p>
     91 
     92 <p>
     93 Refining your writing will be another fascinating challenge on your path to mastery. At
     94 its best, writing can be very satisfying. While it might feel daunting now, in time it
     95 could become something you take real pleasure in.
     96 </p>
     97 
     98 <p>
     99 Yet it can sure feel difficult and daunting to establish yourself in this space. What
    100 should you write about? How should you get started? How often should you publish your
    101 work? Where? When?
    102 </p>
    103 
    104 <p>
    105 It&rsquo;s a lot to take in.
    106 </p>
    107 
    108 <p>
    109 This post contains some advice to anyone aspiring to technical writing on the web. Also
    110 included are some creative writing exercises to help develop your thinking.
    111 </p>
    112 </blockquote>
    113 
    114 <p>
    115 One very interesting part of this article is the template part of it:
    116 </p>
    117 <dl class="org-dl">
    118 <dt>Beginning</dt><dd><i>What are you going to tell me</i></dd>
    119 <dt>Middle</dt><dd><i>The telling</i></dd>
    120 <dt>End</dt><dd><i>What did you tell me</i></dd>
    121 </dl>
    122 </div>
    123 </div>
    124 </section>
    125 </main>
    126 <footer id="postamble" class="status">
    127 <footer>
    128      <small><a href="/" rel="history">Index</a> • <a href="/sitemap.html">Sitemap</a> • <a href="https://dl.sbr.pm/">Files</a></small><br/>
    129      <small class='questions'>Questions, comments ? Please use my <a href="https://lists.sr.ht/~vdemeester/public-inbox">public inbox</a> by sending a plain-text email to <a href="mailto:~vdemeester/public-inbox@lists.sr.ht">~vdemeester/public-inbox@lists.sr.ht</a>.</small><br/>
    130      <small class='copyright'>
    131       Content and design by Vincent Demeester
    132       (<a rel='licence' href='http://creativecommons.org/licenses/by-nc-sa/3.0/'>Some rights reserved</a>)
    133     </small><br />
    134 </footer>
    135 </footer>
    136 </body>
    137 </html>