Welcome to docs.opsview.com

Documentation Style Guidelines

This page describes some general guidelines when writing documentation on this site.

The purpose is to set a consistent and efficient style so readers can understand the information as easily and as clearly as possible. This means more work for the writers!

Structure

Page

Each page should describe its purpose at the beginning. Keep each page to a single purpose.

There should be a beginning, middle and an end:

  • What do you need to make this happen? What is crucial to this exercise? Decide how you should approach this task.
  • Start at the very beginning in simple clear steps – think in a structured way, clarify your thoughts on the subject, decide on a starting point
  • Provide an answer which is relevant only to that subject, and list the expected outcomes/results in a easy scannable form
  • For longer sets of instructions include “before you start” and “after you've finished” sections. These may link off to other resources
  • The main body of documents should be structured in a linear formal that allows the user to carry out the actions one-by-one without being confused or navigating off to other pages.

Namespaces

Always make changes to the opsview-community namespace first. If applicable to a specific enterprise version of Opsview, change the page in the relevant namespace appropriately.

Paragraphs

Breakdown lengthy text into more manageable sections. Identify material that may be better placed on linked pages. Start at the beginning; provide a solution by the end.

Language

Keep it Concise

Choose your words carefully, and any superfluous text needs to be cut. Your meanings must be very clear

Use single words instead of phrases:

Instead of:Use:
a number of many, several
a small number of a few
are in agreement agree
are found to be are
are known to be are
at present now
at the present time now
based on the fact that because
by means of by
despite the fact that although
due to the fact that because

Basics

  • Use academic written, not spoken English
  • English spellings not US – example:
    • Utilise not utilize, colour not color, standardised not standardized
    • Specialised not specialized, rationalised not rationalized
  • Do not use slang or colloquial language, 'text speak' or idioms

Active and Passive Voice

Sentences can be written or spoken in an active or passive voice. In the active voice, the subject of the sentence acts upon something or someone. In the passive voice, the subject is acted upon.

For example:

Active Voice: The manager downloaded the programme.

Passive Voice: The programme was downloaded by the manager. 

Writers should usually use the active voice rather than the passive. It‘s taken to be a more powerful and straightforward form of expression. The active voice also uses fewer words to convey the same message. It is more direct.

Always use the active voice when writing.

Capitals

  1. The first word of every sentence.
  2. The first-person singular pronoun, I.
  3. The first, last, and important words of a title. (Quick Start Guide)
  4. Proper nouns
  5. Specific persons and things: (Barak Obama, the White House)
  6. Specific geographical locations: London, Manchester, Europe
  7. However, do not capitalise locations that aren't being used as names: the north side of the town (north should be lower case)
  8. Days of the week, months, holidays
  9. Do not capitalise names of seasons (spring, summer, fall, autumn, winter)
  10. Races, nationalities, languages: (English, British, African American)
  11. Brand names: Pepsi, Opsera, Barclays Bank

There are some common mistakes with capitalisation. Use the following when referring to the product:

  • Opsview
  • MySQL

Hyphenation

For terms such as Auto-discovery and Multi-tenancy, use hypenation as agreed.

Where headline capitals are used (eg, Notification Methods and Host Groups), hypenation becomes Auto-Discovery and Multi-Tenancy.

Opsview Naming

Opsview comes in three products:

  • Opsview Core
  • Opsview Pro
  • Opsview Enterprise

Use capitals for both terms as these are proper nouns.

Titles, Subtitles and Headings

If you are creating a titles there are many things that need to go into it to make it good. But the basic elements are to

  • keep it short, no more than 80 characters;
  • cut out any extra words, like 'that' and 'to' – even at the expense of proper English (a title is an exception to the norm and can still be understood)
  • find a way to fit your keywords in

Subheadings

A good title can do a lot to draw your audience in. A good set of continuing subtitles will keep them reading. Subtitles, or subheadings, should be used to support your content in a constructive way. They should provide short rest stops for the reader‘s eye, yet move the subject on effectively.

You should use one main title in bold and underlined to indicate a new topic/section/article. Where there are other important sections within that piece – you should use a subtitle, not bold but just underlined (and not indented). Do not have large chunks of text. Even step-by-step instructions which make use of numbered points to break up the content can lose the reader when the points are too long. This is where subtitles come in handy.

Use bullets to indicate quick, efficient instructions, lists or pointers – keep it simple (one, two, three where possible). Keep all your bullets indented equally or they will lose their relevance, and keep all your bullets the same style.

Markup

Use the following markup for the type of text:

Type of Text Markup Result
Filenames ''/usr/bin/filename'' /usr/bin/filename
Commands ''ls -l /etc'' ls -l /etc
Menu Options ''settings => Monitoring Servers'' settings ⇒ Monitoring Servers
URLs http://example.com http://example.com
Quoted application text, such as host templates //Application - Opsview Master// Application - Opsview Master

For menus, do not use subheadings.

If you are referencing a user's webserver, use a URL like:

http://opsview.example.com/xml/opsview.rng

This should then be clear that the server name should be changed to their own server.

The rest of this section is based on examples.

Executing a Series of Commands

State what needs to be done, followed by a code snippet. It should be cut-and-pasteable. Ensure you mention what user the code needs to be run as.

For example:

Run this to restart opsview-web:

su - nagios
/etc/init.d/opsview-web restart

If there is a very long command, break with backslashes with two space indent. For example:

apt-get install opsview opsview-web \
  opsview-core opsview-base opsview-perl \
  libapache2-dev 

Contents of a File

This should be in a single block area. Use syntax highlighting if possible. Available options at dokuwiki documentation.

For example this is the content of crontab -u nagios:

# OPSVIEW-START
# Do not remove comment above. Everything between OPSVIEW-START and OPSVIEW-END
# will be automatically installed as part of an Opsview install/upgrade
0,5,10,15,20,25,30,35,40,45,50,55 * * * * /usr/local/nagios/bin/mrtg_genstats.sh > /dev/null 2>&1
11 3 * * * /usr/local/nagios/bin/rc.opsview cron_daily > /dev/null 2>&1

Using Notes

<note>
Plain note
</note>

<note warning>
Warning
</note>

<note important>
Important note
</note>

Do not overuse!

Screenshots and Images

Screenshots should only contain the Opsview content, not include the browser chrome (unless specifically pointing to browser features).

All screenshots on the same page should use the same browser.

When taking screenshots, zoom out to 80% if necessary.

If you need to highlight a screenshot (to point to an item in the screenshot), use numbers to denote the section and then refer to the number in the text. Use red ovals of 2px width.

References to Nagios® Core

Use Nagios Core for references to:

  • the application, eg To stop the Nagios Core application …

The first use of Nagios Core on each page should include the ®.

Use nagios for references to:

  • the Unix user, eg Change to the nagios user
  • the daemon, eg Check if the nagios daemon is running

When referring to other projects, Core is not added in. For example:

  • Nagios Plugins
  • Nagios Checker
  • Nagios Remote Plugin Executor
Navigation
Print/export
Toolbox