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