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