-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathInstallation-guide.md.html
More file actions
212 lines (130 loc) · 22.1 KB
/
Installation-guide.md.html
File metadata and controls
212 lines (130 loc) · 22.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
<html>
<head>
<title>Installation-guide.md</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<style type="text/css">
.s0 { color: #cf8e6d;}
.s1 { color: #bcbec4;}
.s2 { color: #bcbec4;}
.s3 { color: #56a8f5;}
</style>
</head>
<body bgcolor="#1e1f22">
<table CELLSPACING=0 CELLPADDING=5 COLS=1 WIDTH="100%" BGCOLOR="#606060" >
<tr><td><center>
<font face="Arial, Helvetica" color="#000000">
Installation-guide.md</font>
</center></td></tr></table>
<pre><span class="s0"># </span><span class="s2">Installation guide</span>
<span class="s0">> </span><span class="s2">If you need more information about how to fill in this template, read the accompanying </span><span class="s1">[</span><span class="s2">guide</span><span class="s1">](</span><span class="s3">https://gitlab.com/tgdp/templates/-/blob/v1.2.0/installation-guide/guide_installation-guide.md</span><span class="s1">)</span><span class="s2">.</span>
<span class="s1">></span>
<span class="s1">> </span><span class="s2">This template includes writing instructions and boilerplate text that you can customize, use as-is, or completely replace with your own text. This text is indicated in {</span><span class="s1">(</span><span class="s2">curly brackets</span><span class="s1">)</span><span class="s2">}. Make sure you replace the placeholders with your own text.</span>
<span class="s0">## </span><span class="s2">Introduction</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">The installation guide template includes information on writing procedures for successfully installing {product name</span><span class="s1">)</span><span class="s2">}. {</span><span class="s1">(</span><span class="s2">Insert your preferred description of the installation process.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Optional</span><span class="s1">: </span><span class="s2">Add a demo GIF that shows what the installed project would look like or link to a sandbox or playground to test out the product and explore its features.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">## </span><span class="s2">Installation types</span>
<span class="s2">This guide explains the steps and instructions required to install {</span><span class="s1">(</span><span class="s2">product name</span><span class="s1">)</span><span class="s2">} on supported operating systems. It also explains how to configure, start, and uninstall {</span><span class="s1">(</span><span class="s2">product name</span><span class="s1">)</span><span class="s2">}}.</span>
<span class="s2">{Include a table to capture the different installation types, such as</span><span class="s1">:</span>
<span class="s0">* </span><span class="s2">Supported operating systems</span>
<span class="s0">* </span><span class="s2">The type of product installed </span><span class="s1">(</span><span class="s2">if provided in different versions, such as Main and Lite version</span><span class="s1">)</span>
<span class="s0">* </span><span class="s2">Cloud providers, such as CodeSpaces, CodeSandBox, GitPod, etc.,</span><span class="s1">) </span><span class="s2">including a link to the right heading for all options.}</span>
<span class="s0">| </span><span class="s1">**Type** </span><span class="s0">| </span><span class="s1">**Description** </span><span class="s0">| </span><span class="s1">**More information** </span><span class="s0">|</span>
<span class="s0">| --------- | ----------------- | ------------------- |</span>
<span class="s0">| </span><span class="s1">{(Name of installation type)} </span><span class="s0">| </span><span class="s1">{(Description of installation type)} </span><span class="s0">| </span><span class="s1">{(Link to the relevant installation steps section)} </span><span class="s0">|</span>
<span class="s0">| </span><span class="s1">{(Name of installation type)} </span><span class="s0">| </span><span class="s1">{(Description of installation type)} </span><span class="s0">| </span><span class="s1">{(Link to the relevant installation steps section)} </span><span class="s0">|</span>
<span class="s0">## </span><span class="s2">Overview</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">This section is optional.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Add a list of the available project versions, link to the installation guide for that version, and highlight the latest, beta, or stable version as listed in the following table</span><span class="s1">:)</span><span class="s2">}</span>
<span class="s0">| </span><span class="s1">**Version** </span><span class="s0">| </span><span class="s1">**Build** </span><span class="s0">| </span><span class="s1">**Release Date** </span><span class="s0">| </span><span class="s1">**Status** </span><span class="s0">|</span>
<span class="s0">| -------- | --------- | -------- | ------- |</span>
<span class="s0">| </span><span class="s1">[V {(versionNumber)}](#link) </span><span class="s0">| </span><span class="s1">{(versionNumber release)} </span><span class="s0">| </span><span class="s1">{(dd/mm/yyyy)} </span><span class="s0">| </span><span class="s1">{(Latest)} </span><span class="s0">|</span>
<span class="s0">| </span><span class="s1">[V {(versionNumber)}](#link) </span><span class="s0">| </span><span class="s1">{(versionNumber release)} </span><span class="s0">| </span><span class="s1">{(dd/mm/yyyy)} </span><span class="s0">| </span><span class="s1">{(Beta)} </span><span class="s0">|</span>
<span class="s0">| </span><span class="s1">[V {(versionNumber)}](#link) </span><span class="s0">| </span><span class="s1">{(versionNumber release)} </span><span class="s0">| </span><span class="s1">{(dd/mm/yyyy)} </span><span class="s0">| </span><span class="s1">{(Stable)} </span><span class="s0">|</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Explain the intended result of the installation, such as the commands, command aliases, major flags, available plugins, files downloaded, or application programs.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Add a sequential end-to-end summary of the installation process that can serve as a quick link or reference section for users as listed in the following table</span><span class="s1">:)</span><span class="s2">}</span>
<span class="s0">| | </span><span class="s1">**Process** </span><span class="s0">| </span><span class="s1">**More information** </span><span class="s0">|</span>
<span class="s0">| ---- | ------------ | -------------------- |</span>
<span class="s0">| </span><span class="s1">1. </span><span class="s0">| </span><span class="s1">Before installing, check the system requirements to ensure your computer is supported in the latest version of {(product name)}. </span><span class="s0">| </span><span class="s1">{(Link to relevant documents)} </span><span class="s0">|</span>
<span class="s0">| </span><span class="s1">2. </span><span class="s0">| </span><span class="s1">Check the system prerequisites to install all the required {(software, dependencies, tools.)}. </span><span class="s0">| </span><span class="s1">{(Link to relevant documents)} </span><span class="s0">|</span>
<span class="s0">| </span><span class="s1">3. </span><span class="s0">| </span><span class="s1">{(List additional steps.)} </span><span class="s0">| </span><span class="s1">{(Link to relevant documents)} </span><span class="s0">|</span>
<span class="s0">| </span><span class="s1">4. </span><span class="s0">| </span><span class="s1">Verify that the installation was successful. </span><span class="s0">| </span><span class="s1">{(Link to relevant documents)} </span><span class="s0">|</span>
<span class="s0">## </span><span class="s2">System requirements</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Start by breaking this into sub-sections based on the number of installation types </span><span class="s1">(</span><span class="s2">product type, operating system, or cloud-especially for projects that require self-hosting to work</span><span class="s1">)</span><span class="s2">. Based on your use case, you can use this section reversely by having the installation type as the heading and system requirements for that type as a sub-section.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Mention for all installation types.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">## </span><span class="s2">Before you begin</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">List and highlight all the required prerequisites here. Consider making this a table.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">Before installing {</span><span class="s1">(</span><span class="s2">version number</span><span class="s1">)</span><span class="s2">}, ensure you have</span><span class="s1">:</span>
<span class="s0">* </span><span class="s2">{</span><span class="s1">(</span><span class="s2">Prerequisite one</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">* </span><span class="s2">{</span><span class="s1">(</span><span class="s2">Prerequisite two</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">* </span><span class="s2">{</span><span class="s1">(</span><span class="s2">Prerequisite three</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Include prerequisites for all installation types.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">| </span><span class="s1">**Type** </span><span class="s0">| </span><span class="s1">**Prerequisites** </span><span class="s0">| </span><span class="s1">**Note(s)** </span><span class="s0">|</span>
<span class="s0">| --------- | ----------------- | ------------ |</span>
<span class="s0">| </span><span class="s1">{(Installation type name)} </span><span class="s0">| </span><span class="s1">{(Installation type prerequisites)} </span><span class="s0">| </span><span class="s1">{(Important considerations)} </span><span class="s0">|</span>
<span class="s0">| </span><span class="s1">{(Installation type name)} </span><span class="s0">| </span><span class="s1">{(Installation type prerequisites)} </span><span class="s0">| </span><span class="s1">{(Important considerations)} </span><span class="s0">|</span>
<span class="s0">## </span><span class="s2">Installation steps</span>
<span class="s2">The following procedure explains how to install {</span><span class="s1">(</span><span class="s2">installation type name</span><span class="s1">)</span><span class="s2">} and {</span><span class="s1">(</span><span class="s2">optional version number</span><span class="s1">)</span><span class="s2">}.</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Provide a short introduction to the step-by-step procedure based on the installation type.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">Get started with {</span><span class="s1">(</span><span class="s2">version number</span><span class="s1">)</span><span class="s2">} by {</span><span class="s1">(</span><span class="s2">write the first step a user needs to start the installation. Use a verb to start.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">### </span><span class="s2">Step 1 - One-sentence description of the step</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Optionally, introduce this section with brief explanatory text.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Continue with a list section if these steps include a sequence of instructions</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Optional</span><span class="s1">: </span><span class="s2">include a code snippet or relevant screenshot that helps your users complete the steps.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Optional</span><span class="s1">: </span><span class="s2">show the result of completing this step, such as a text output or an image</span><span class="s1">)</span><span class="s2">.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">#### </span><span class="s2">1.1. Substep 1 - One-sentence description of the step</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Optionally, introduce this section with brief explanatory text.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Continue with a list section if these steps include a sequence of instructions</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">#### </span><span class="s2">1.2. Substep 2 - One-sentence description of the step</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Optionally, introduce this section with brief explanatory text.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Continue with a list section if these steps include a sequence of instructions.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">### </span><span class="s2">Step 2 - One-sentence description of the step</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Optionally, introduce this section with brief explanatory text.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Continue with a list section if these steps include a sequence of instructions.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">## </span><span class="s2">Verify installation</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Include test commands, intended outputs, or other steps to confirm the installation was successful.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">## </span><span class="s2">Post installation</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Provide an overview of options or link to other relevant documentation once installation has been completed. Also, account for anticipated problems during or after installation.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Optinal</span><span class="s1">: </span><span class="s2">include short introduction text.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">### </span><span class="s2">Configuration options</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Provide information regarding post-installation configuration options.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Describe the requirements for configuring the installed product.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Link to relevant documentation if needed.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">### </span><span class="s2">Upgrade options</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Provide information regarding upgrade options, also known as an update options.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Describe how to install updates from a range of possible options.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Provide a link to available updates with specific version numbers, release dates, and key features.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">Example</span><span class="s1">: </span><span class="s2">To begin the system updates</span><span class="s1">:</span>
<span class="s0">1. </span><span class="s2">Choose the version number.</span>
<span class="s0">2. </span><span class="s2">Download the update at </span><span class="s1">[</span><span class="s2">link</span><span class="s1">](</span><span class="s3">http://example.com</span><span class="s1">)</span><span class="s2">.</span>
<span class="s0">3. </span><span class="s2">Double-click the update file.</span>
<span class="s0">4. </span><span class="s2">Additional steps as needed.</span>
<span class="s0">### </span><span class="s2">Downgrade options</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Provide information regarding downgrading the version installed.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">### </span><span class="s2">Uninstallation options</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Provide information regarding uninstalling the product, software, SDK, package, library, framework installed.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">## </span><span class="s2">Troubleshooting</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">This section helps solve problems encountered during installation. Start with a problem statement, then indicate the cause</span><span class="s1">(</span><span class="s2">s</span><span class="s1">) </span><span class="s2">and provide a solution. Additional information can be added </span><span class="s1">(</span><span class="s2">e.g., restart the computer</span><span class="s1">))</span><span class="s2">}.</span>
<span class="s2">{Add a warning note and highlight in color if the action has the potential to affect security.</span>
<span class="s2">Communicating with the product engineers and programmers is essential to keep this section up-to-date.}</span>
<span class="s0">### </span><span class="s2">{</span><span class="s1">(</span><span class="s2">Problem title</span><span class="s1">: </span><span class="s2">...</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Optional</span><span class="s1">: </span><span class="s2">More details about the </span><span class="s1">**</span><span class="s2">problem</span><span class="s1">**</span><span class="s2">.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Optional</span><span class="s1">: </span><span class="s2">More details about the </span><span class="s1">**</span><span class="s2">cause</span><span class="s1">(</span><span class="s2">s</span><span class="s1">)** </span><span class="s2">of the problem.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s1">**</span><span class="s2">Solution</span><span class="s1">**: </span><span class="s2">{</span><span class="s1">(</span><span class="s2">Solution to the problem...</span><span class="s1">)</span><span class="s2">}</span>
<span class="s1">**</span><span class="s2">Contact</span><span class="s1">**: </span><span class="s2">{</span><span class="s1">(</span><span class="s2">Support/contact information for issue reports and feedback...</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">### </span><span class="s2">{</span><span class="s1">(</span><span class="s2">Problem title</span><span class="s1">: </span><span class="s2">...</span><span class="s1">)</span><span class="s2">}</span>
<span class="s2">...</span>
<span class="s0">## </span><span class="s2">Next steps</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Include what to do after a successful installation, such as a recommended next step or links to further recommended documentation.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">## </span><span class="s2">Product version history</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">History section with major changes to the installation guide tabulated following the Major.Minor.Patch semantic versioning specification.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">## </span><span class="s2">Definition of terms</span>
<span class="s2">{</span><span class="s1">(</span><span class="s2">Optional</span><span class="s1">: </span><span class="s2">Provide a glossary table describing the terms, acronyms, and abbreviations used in the installation guide.</span><span class="s1">)</span><span class="s2">}</span>
<span class="s0">| </span><span class="s1">**Term** </span><span class="s0">| </span><span class="s1">**Meaning** </span><span class="s0">|</span>
<span class="s0">| ------------------------------------- | ------------ |</span>
<span class="s0">| </span><span class="s1">{(Term, acronym, or abbreviation)} </span><span class="s0">| </span><span class="s1">{(Provide a definition of the term or acronym or abbreviation used in this guide.)} </span><span class="s0">|</span>
<span class="s0">| </span><span class="s1">{(Term, acronym, or abbreviation)} </span><span class="s0">| </span><span class="s1">{(Provide a definition of the term or acronym or abbreviation used in this guide.)} </span><span class="s0">|</span>
<span class="s0">---</span>
<span class="s0">> </span><span class="s2">Explore other templates from </span><span class="s1">[</span><span class="s2">The Good Docs Project</span><span class="s1">](</span><span class="s3">https://thegooddocsproject.dev/</span><span class="s1">)</span><span class="s2">. Use our </span><span class="s1">[</span><span class="s2">feedback form</span><span class="s1">](</span><span class="s3">https://thegooddocsproject.dev/feedback/?template=Installation%20guide</span><span class="s1">) </span><span class="s2">to give feedback on this template.</span>
</pre>
</body>
</html>