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   <span class="tag"><span class="docs">docs</span> <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 “get-in”, 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’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>