User Guide Content Guidelines¶
This section contains directions to assist in both writing new content and reviewing existing content for NetEye‘s user guide.
This section is organized as follows. We first introduce some Terminology, then give examples of Roles and Directives, and finally show how to write Command Line Prompts in code blocks.
Language Style¶
This section lists conventions we are using and that need to be followed when writing new content or updating existing content.
Rule |
Name |
Description |
---|---|---|
L1 |
Active tone |
Use active voice instead of passive, unless the latter is required by the context. Compare (passive): To begin monitoring an Alyvix node, the node must first be created in the Director module as an Icinga Host with (active): To begin monitoring an Alyvix node, you should first create one in the Director module as an Icinga Host |
L2 |
Direct tone |
Use direct, personal tone when giving specific instructions to users, e.g.: Go to the Downloads section of the NetEye blog, then move to NetEye –-> GPG public key and save public-gpg-key. |
L3 |
Section titles |
Use nouns or noun groups instead of imperative sentences in section titles of all levels, e.g. Manual blockchain verification instead of Manually verify blockchain |
L4 |
Titles capitalization |
Use Capital Letters in section titles of all levels, with the exception of auxiliary words, e.g. articles, prepositions, and the like |
L5 |
Commas |
Do not use a comma after i.e. and e.g. |
Terminology¶
Consistent use of terminology and style of words is mandatory in a guide.
Namimg¶
Rule |
Description |
---|---|
N1 |
Capitalise all names that relate to NetEye, including its
modules and all the terms that refer to NetEye elements. Each term
should have an entry in the glossary, so it can be referenced by
using the |
N2 |
NetEye specific terms do not require articles. This refers to both original NetEye terminology, e.g. NetEye, Single Node, and terms related to software integrated with NetEye, e.g. Telegraf, Icinga 2, not the Telegraf, the Icinga 2 |
NetEye Architecture¶
All terms related to NetEye are written with an uppercase first letter, except for NetEye itself, for example:
Rule |
Description |
---|---|
NE1 |
NetEye is written in Pascal Case / upper camel case. Also substitutions
have been added to the configuration: |
NE2 |
(NetEye) Single Node, (NetEye) Cluster Node, (NetEye) Satellite Node, (NetEye) Master-Satellite |
NE3 |
Elastic-only, Voting-only, but note that sometimes they are shortened as (E) and (V), respectively |
NE4 |
Single Purpose nodes (used to denote both Elastic-only and Voting-only nodes) |
Note
In rule NE2, the NetEye prefix should always be used, because it is part of the name, but it can be omitted on a case-by-case basis only if it becomes redundant, for example in paragraphs in which the term is used multiple times.
As additional remark, do not capitalise terms like cluster, cluster node, etc, if you are not referring to NetEye elements, for example: RHEL 8 cluster. Pay also attention to capitalise properly: Elastic-only is correct, Elastic-Only is not.
Various Expressions¶
to tell readers who they should contact for help/information, copy and paste (you might need to change the introductory please refer to) the following source code:
please refer to the official channels: sales, consultants, or |support|_.
It will render as: please refer to the official channels: sales, consultants, or support portal.
Hint
The replacement
|support|_
will always expand to support portal (with hyperlink).
Configuration Options, GUI Elements, Files/Paths¶
Rule |
Description |
---|---|
C1 |
The name of configuration options and of elements in the GUI is always in boldface: this includes labels, tab names (e.g. Host, Services, History), but not buttons. |
C2 |
To denote a button or an interactive element of a GUI,
use the |
C3 |
Values of configuration options, including default and suggested values, are written in italics, e.g. ‘The Retention Policy defaults to 15 days. To avoid resource exhaustion in case of high traffic, you can reduce it to 10 or 7 days.’ |
C4 |
When mentioning files or (standard) filesystem locations
always use the full path and the |
C5 |
Technical terms, like for example the name of databases
and of their tables, should be written in monospace font using the
double backticks, like e.g. * See the |
Roles¶
Roles are used inline with the content to identify and highlight certain portions of text.
:term:
It creates a cross-reference to a term defined in the glossary. The term must exist in the glossary. Example: :term:`Downtime` becomes Downtime.
:abbr:
It is used to create tootips when hovering. Example: :abbr:`SLM (Service Level Management)` becomes SLM
:file:
A role used to show the location of a file on the filesystem. Example: :file:`/neteye/shared/icingaweb2/conf/authentication.ini` becomes
/neteye/shared/icingaweb2/conf/authentication.ini
:command:
Similar to previous, it shows a command. Example: :command:`neteye status` becomes neteye status
:guilabel:
This role is used for (G)UI’s interactive parts (mostly buttons). Example: :guilabel:`Add a new user` becomes Add a new user.
:menuselection:
This helps when a user needs to be guided through (G)UI’s menus. Example: :menuselection:`Configuration / Authentication / Users` becomes
:phone:
Phone class has to have white-space: nowarp. +39 0471 56 41 01
:ref:
Used to create a reference to a label (which can be in every file, not just the current one) and create a clickable link, for example: :ref:`ug-terminology` becomes Terminology.
It can be used also with a custom text. For example: Please check the :ref:`default terminology <ug-terminology>` becomes Please check the default terminology
:numref:
Create a numbered reference to a figure or code listing. It works as
:ref:
but outputs the number of the figure. :numref:`figure-neteye-cluster` becomes Fig. 3. When using:ref:
with a label, instead of the number, the caption of the figure is used: :ref:`figure-neteye-cluster` becomes The NetEye cluster architecture..
Directives¶
Directives are used to separate content from surrounding text and are used to emphasise content or to provide additional information to the surrounding text.
This is a rubric
Rubric is used to create a non-sectioning heading, i.e. a heading that does not appear in the ToC. Rubrics are used in this section (see above). Example:
.. rubric:: This is a ``rubric``
seealso
Useful directive to add bibliography, (external) reference articles, or other content in the UG. Example:
.. seealso:: `Grafana customisation
<https://www.neteye-blog.com/2021/03/how-to-customize-a-grafana-component/>`_
is explained in the `NetEye Blog <https://neteye-blog.com/>`_.
See also
Grafana customisation is explained in the NetEye Blog.
Admonitions
Admonitions are used to draw attention on something just written. Examples:
.. note:: Remember to save the setting.
.. hint:: The default value is **5**.
.. warning:: Make a backup copy before upgrading!
.. tip:: Check also Figure 3.
Note
Remember to save the setting.
Hint
The default value is 5.
Warning
Make a backup copy before upgrading!
Tip
Check also Figure 3.
topic
A topic is used to extend and complement the knowledge of the surrounding text, but reading it is not necessary to the actual content of the page/text. Example:
.. topic:: When to use roles and directives in Sphinx
Roles and directives provide a great means to improve text layout
and organisation, allowing the reader to find quickly the
important pieces of the documentation.
Command Line Prompts¶
The following prompts must be used whenever writing a code-block::
.
Type |
Description |
Command Example |
---|---|---|
generic neteye command |
commands that can be executed on every neteye node of the neteye architectuyre |
|
generic neteye cluster command |
commands that can be executed only on a neteye cluster |
|
neteye cluster active node specific command |
commands that need to be executed on a neteye cluster active node |
|
neteye cluster other node specific command |
commands that need to be executed on other nodes of a neteye cluster |
|
neteye cluster standby node |
commands that need to be executed on all nodes that are in standby |
|
neteye cluster not-standby node |
commands that need to be executed on the neteye cluster node that is not in standby (there is only one) |
|
neteye cluster node where a resource is running |
commands that need to be executed on a neteye cluster node where a specific resource is running |
|
neteye statellite specific command |
commands that need to be executed on a neteye satellite |
sat# |
neteye Voting-only |
Command to run on Voting-only nodes |
|
neteye Elastic-only |
Command to run on Elastic-only nodes |
|
neteye InfluxDB-only |
Command to run on InfluxDB-only nodes |
|