Updated git submodules
[docs.git] / docs / templates / template-user-guide.rst
1 ####################
2 <Feature> User Guide
3 ####################
4
5 Refer to this template to identify the required sections and information
6 that you should  provide for a User Guide. The user guide should contain
7 configuration, administration, management, using, and troubleshooting
8 sections for the feature.
9
10 Overview
11 ========
12
13 Provide an overview of the feature and the use case. Also include the
14 audience who will use the feature. For example, audience can be the
15 network administrator, cloud administrator, network engineer, system
16 administrators, and so on.
17
18 <Feature> Architecture
19 ======================
20
21 Provide information about feature components and how they work together.
22 Also include information about how the feature integrates with
23 OpenDaylight. An architecture diagram could help.
24
25 .. note:: Please *do not* include detailed internals that somebody
26           using the feature wouldn't care about. For example, the fact
27           that there are four layers of APIs between a user command and
28           a message being sent to a device is probably not useful to
29           know unless they have some way to influence how those layers
30           work and a reason to do so.
31
32
33 Configuring <feature>
34 =====================
35
36 Describe how to configure the feature or the project after installation.
37 Configuration information could include day-one activities for a project
38 such as configuring users, configuring clients/servers and so on.
39
40 Administering or Managing <feature>
41 ===================================
42
43 Include related command reference or  operations that you could perform
44 using the feature. For example viewing network statistics, monitoring
45 the network, generating reports, and so on.
46
47 .. note: Ensure that you create a step procedure whenever required and
48          avoid concepts.
49
50 For example:
51
52 To configure L2switch components perform the following steps.
53
54 #. Step 1:
55 #. Step 2:
56 #. Step 3:
57
58 Tutorials
59 =========
60
61 *optional*
62
63 If there is only one tutorial, you skip the "Tutorials" section and
64 instead just lead with the single tutorial's name. If you do, also
65 increase the header level by one, i.e., replace the carets (^^^) with
66 dashes (- - -) and the dashes with equals signs (===).
67
68 <Tutorial Name>
69 ---------------
70
71 Ensure that the title starts with a gerund. For example using,
72 monitoring, creating, and so on.
73
74 Overview
75 ^^^^^^^^
76
77 An overview of the use case.
78
79 Prerequisites
80 ^^^^^^^^^^^^^
81
82 Provide any prerequisite information, assumed knowledge, or environment
83 required to execute the use case.
84
85 Target Environment
86 ^^^^^^^^^^^^^^^^^^
87
88 Include any topology requirement for the use case. Ideally, provide
89 visual (abstract) layout of network diagrams and any other useful visual
90 aides.
91
92 Instructions
93 ^^^^^^^^^^^^
94
95 Use case could be a set of configuration procedures. Including
96 screenshots to help demonstrate what is happening is especially useful.
97 Ensure that you specify them separately. For example:
98
99 Setting up the VM
100 """""""""""""""""
101
102 To set up a VM perform the following steps.
103
104 #. Step 1
105 #. Step 2
106 #. Step 3
107
108 Installing the feature
109 """"""""""""""""""""""
110
111 To install the feature perform the following steps.
112
113 #. Step 1
114 #. Step 2
115 #. Step 3
116
117 Configuring the environment
118 """""""""""""""""""""""""""
119
120 To configure the system perform the following steps.
121
122 #. Step 1
123 #. Step 2
124 #. Step 3