main
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>
33The Grand Unified Theory of Documentation
34— David Laing
35</p>
36
37<p>
38There is a secret that needs to be understood in order to write good software
39documentation: there isn’t one thing called documentation, there are four.
40</p>
41
42<p>
43They are: tutorials, how-to guides, technical reference and explanation. They represent
44four different purposes or functions, and require four different approaches to their
45creation. Understanding the implications of this will help improve most documentation -
46often immensely.
47</p>
48</blockquote>
49
50<p>
51This is a set of resources around how setup a system to document your software/product
52correctly. 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>
57Usually the most important to “get-in”, and usually not very well done.</li>
58<li>How-to Guides — <i>problem-oriented</i>
59Series 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>
71Given 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>
88Do you struggle to write blog posts? Developing your craft when it comes to writing can be
89as intimidating as the buggiest code.
90</p>
91
92<p>
93Refining your writing will be another fascinating challenge on your path to mastery. At
94its best, writing can be very satisfying. While it might feel daunting now, in time it
95could become something you take real pleasure in.
96</p>
97
98<p>
99Yet it can sure feel difficult and daunting to establish yourself in this space. What
100should you write about? How should you get started? How often should you publish your
101work? Where? When?
102</p>
103
104<p>
105It’s a lot to take in.
106</p>
107
108<p>
109This post contains some advice to anyone aspiring to technical writing on the web. Also
110included are some creative writing exercises to help develop your thinking.
111</p>
112</blockquote>
113
114<p>
115One 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>