Structure Overview

NIC systems information is organized into a number of categories. This document will attempt to explain the divisions, and act as a guide to adding further information.

Namespace selection

Proper namespace selection will ensure that the document is correctly indexed for search and reference purposes.

Documents should be created in the form: [[CategoryName:DocumentTitle]]
For example, a guide to installing Octave is at: Software:Octave

If the documentation is specific to a host, use the same structure, but with a slash followed by the host name or type that the information is specific to: [[CategoryName:DocumentTitle/Host]]
For example, Software:Octave/Neuronic

Documents should also always contain a Category tag. This tag will make sure that they are automatically linked to from their Category page.
For example, any document in the Software section should contain the following wikitext: [[Category:Software]]

Section Specific Documentation

Servers

Host-specific hardware and software documentation

Server documentation is divided into two host classes: Compute and Infratstructure nodes. These two types are futher divided by architecture. New hosts should be added to the end of the list in their proper section. The link should reference the host's class and short hostname (not FQDN) in the form:

 * [[Class:Hostname]]

Each host's page should have information about the hardware, software, and an example of common command output on a functioning system.
See the following page for a template: Template:host

Proceedures

Guides to common procedures such as creating a new user account or configuring LDAP

Any guide that does not fit into another section should go here.

Info

Miscellaneous useful info, such as user and hardware lists

Any general collection of information should go here.

Services

Software installed and running on one or more hosts to provide a network service

Documentation on the main Service page should include:

• What service the software provides
• Where to find authoritative documentation on the software
• Generic installation or operating instructions
• Any other information not specific to a specific host
• A list of hosts the service is installed and running on
• What ports or sockets does the service listen on?
• What firewall rules are necessary to permit the service to be accessed?
• Where does the service log to?
• Where are the configuration files stored?
• What processes should be running while the service is running?
• How is the service started or stopped?

The list of hosts from the final item above should contain links to host-specific documentation pages as described in the namespace section above. Those pages should discuss:

• How the service was installed
  • Package manager? Which one?
  • Built from source? If so, what build options were used? Where was it installed to?
• Any notes about running the service unique to this host

If any of the above information is provided on the generic service page, and it is accurate on this host, it may be ommited.

Compilers

Specialized vendor-distributed compilers Documentation on the main Compiler page should include:

• What purpose the compiler serves
• Where to find authoritative documentation on the software
• Any licensing or registration information
• A list of hosts the compiler is installed on

The list of hosts from the final item above should contain links to host-specific documentation pages as described in the namespace section above. Those pages should discuss:

• How the compiler was installed
• Any notes about using the compiler unique to this host
• Instructions for compiling and linking with this compiler
• Are there configuration files? Where are they stored?

Software

Other software packages that are not compilers or services

Documentation on the main Software page should include:

• What purpose the software serves
• Where to find authoritative documentation on the software
• Generic installation or operating instructions
• Instructions for compiling and linking against any libraries provided by this package
• Are there configuration files? Where are they stored?
• Any other information not specific to a specific host
• A list of hosts the software is installed on

The list of hosts from the final item above should contain links to host-specific documentation pages as described in the namespace section above. Those pages should discuss:

• How the service was installed
  • Package manager? Which one?
  • Built from source? If so, what build options were used? Where was it installed to?
• Any notes about using the software unique to this host

If any of the above information is provided on the generic service page, and it is accurate on this host, it may be ommited.