Structure Overview: Difference between revisions
Nic-systems (talk | contribs) No edit summary |
Nic-systems (talk | contribs) No edit summary |
||
| (4 intermediate revisions by the same user not shown) | |||
| Line 4: | Line 4: | ||
Proper namespace selection will ensure that the document is correctly indexed for search and reference purposes. | Proper namespace selection will ensure that the document is correctly indexed for search and reference purposes. | ||
Documents should be created in the form: '''<nowiki>[[CategoryName:DocumentTitle]]</nowiki><br> | Documents should be created in the form: '''<nowiki>[[CategoryName:DocumentTitle]]</nowiki>'''<br> | ||
For example, a guide to installing | For example, a guide to installing Octave is at: [[Software:Octave]]<br> | ||
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: '''<nowiki>[[CategoryName:DocumentTitle/Host]]</nowiki><br> | 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: '''<nowiki>[[CategoryName:DocumentTitle/Host]]</nowiki><br> | ||
For example, | 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.<br> | Documents should also always contain a Category tag. This tag will make sure that they are automatically linked to from their Category page.<br> | ||
For example, any document in the Software section should contain the following wikitext: '''<nowiki>[[Category:Software]]</nowiki> | For example, any document in the Software section should contain the following wikitext: '''<nowiki>[[Category:Software]]</nowiki>''' | ||
== Section Specific Documentation == | == Section Specific Documentation == | ||
| Line 19: | Line 19: | ||
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: <br> | 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: <br> | ||
<pre> * [[Class:Hostname]]</pre> | |||
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: | Each host's page should have information about the hardware, software, and an example of common command output on a functioning system.<br> | ||
See the following page for a template: | |||
[[Template:host]] | [[Template:host]] | ||
| Line 37: | Line 38: | ||
'''Software installed and running on one or more hosts to provide a network service''' | '''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 === | === Compilers === | ||
'''Specialized vendor-distributed 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 === | === 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. | |||
Latest revision as of 19:24, 4 August 2006
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.