One of the most difficult tasks associated with system administration is maintaining a centralized documentation repository that is current, comprehensive, and inclusive of all systems. The documentation repository is also a key component of any business continuity plan and provides the basis of all training, support, maintenance, and disaster recovery efforts. This article provides a structure, configuration, and automated methodology for maintaining a wiki server oriented around technical documentation for IBM® AIX® implemented using business continuity concepts.
The wiki server discussed here is based on MediaWiki software and provides a collaborative environment for writing and maintaining a documentation repository. In addition to the collaborative aspects, it also creates a standardized look-and-feel for all documents in your repository. The structure provided in this article provides an easy to maintain environment for all contributors to the repository.
Manual vs. automated documentation
One of the difficulties with technical documentation is that as soon as it is written, it is obsolete, out-of-date, and unreliable. This is because most systems in a modern data center environment are dynamic and always under continuous upgrades, improvements, and tuning. Because of the dynamic nature of a modern data center, if the technical documentation is being written manually, then the documentation can never be reliable. Writing documentation takes time and most administrators do not have the time to document fully changes to every system on an immediate basis. There are always higher priorities and crisis that take precedence over updating system documentation.
One of the overriding guidelines of this article is to convince system administrators to stop writing documentation and, instead, they should generate and upload documentation automatically to a centralized documentation server. Any time spent by a system administrator writing documentation is wasted effort, because the moment the documentation is complete, it is obsolete. All documentation in a data center environment must be automatically generated on a scheduled basis (hourly, daily, weekly, monthly). System administrators should spend their time writing automation processes for generating documentation, not writing documentation. And as a more generalized statement, the job of an AIX System administrator is to automate all tasks, including documentation.
Switching from a manual writing task to an automated process for generating technical documentation requires the administrators to write programs and scripts for automating these processes. Manually written technical documentation is usually a tedious, boring, and time consuming task. As a result, most administrators avoid it like the plague. By changing this task from manual writing to a programming task, it will re-engage the administrators because programming is a much more interesting task. Allowing them to update and improve the automated processes keeps them engaged. The result could be that the technical documentation could always be up-to-date and reliable.
A large amount of effort in system administration is simply training and retraining system administrators as they enter and leave an organization. This effort can be significantly reduced by providing a standardized and automated documentation repository oriented around a business continuity design. This repository will enable administrators to be immediately productive and communicate expectations.
Another benefit from automatically generating technical documentation is a reduced workload on the administrators which will result in an overall cost savings for managing the business.
Because of the dynamic nature of the modern data center and the workload imposed upon the administrators, technical documentation must always be generated from the systems and applications to ensure it is up-to-date, consistent, and reliable. A part of any business continuity plan must be a requirement for automatically generating technical documentation.
The use of the term "business continuity" here may be confusing to some of those reading this article because many organizations equate business continuity with disaster recovery. For the purpose of this article, these terms are not equivalent. The term "business continuity" as used in this article is defined as:
"Business continuity consists of the activities performed on a daily basis to ensure the business operates normally today, tomorrow, and beyond. The business continuity plan may be thought of as a methodology or as an enterprise wide mentality of conducting day-to-day business."
The wiki structure for AIX technical documentation
To facilitate the automation process of generating technical documentation, a centralized documentation repository must be created that will allow systems anywhere in the world to create/upload/update their associated documentation. It should also provide a standardized look-and-feel as well as a standardized structure for the documentation.
The best solution currently available that fulfills all of the requirements is a "wiki" server. The wiki provides a collaborative documentation environment that maintains document histories, security, look-and-feel, and permits almost boundless customization. There are numerous wiki servers available; this article will focus on the open source wiki server from “MediaWiki”. This wiki server can be freely downloaded from http://www.mediaWiki.org.
However, simply downloading and installing a wiki server for use as a centralized documentation repository is not enough. There must be a structure associated with the server to ensure the documentation is organized in a coherent and cohesive manner. The structure chosen for discussion in this article is a business continuity structure. This type of documentation structure is all-encompassing for a modern data center environment and provides the flexibility needed to support any business function scenario. Provided in this article is a business continuity structure, configuration, and methodology for building and maintaining a wiki server for your IBM AIX technical documentation.
Another difficult task associated with maintaining a centralized documentation repository is attempting to enforce standards for the documents in the repository. By implementing a centralized documentation repository based on a standardized business continuity structure, the enforcement task becomes much easier. Predefined categories are selected (and required) at the time the documents are uploaded to the repository, thereby eliminating some of the guess work associated with organizing the data in the repository. As an added bonus, a system administration methodology emerges from the repository structure for building, supporting, and maintaining large worldwide, multi-data center IBM AIX environments. The methodology details the entire life cycle of an IBM AIX system, from planning and deployment, through decommission and reclamation.
The wiki environment helps to create a standardized look-and-feel for your documentation repository; however, searching and locating the desired documentation can be troublesome. The business continuity category structure provided in this article provides and easy to maintain environment for all contributors to the repository and incorporates the following:
Category structures for business continuity
- Organizational structure
- Resource utilization
- Category structures for disaster recovery
- Business impact analysis
- Service level agreements, RPO, RTO
- Threats and risks
- Mitigation and contingencies
- Backup and restore procedures
- Recovery scenarios
- Recovery testing
- Command center
- Category structures for shell scripts.
- Category structures for e-business
The objective of the business continuity wiki structure is to consolidate and automate the technical documentation of IBM AIX systems in data centers worldwide.
Automation scripts for user interaction with a wiki server
To automate the process of building the business continuity wiki structure, several shell scripts are provided. These scripts automate the processes of uploading files, creating new pages, modifying existing pages, creating/modifying categories, creating/modifying templates, and so on.
wikiAutoLoad is an automated wiki content uploading script that provides the shell programmer or system administrator with an automated mechanism for uploading wiki content to a MediaWiki server. This shell script can be run from any system in an organization to upload information automatically to a centralized wiki documentation server
wikiAutoLoad provides the following features:
- Dynamic ability to upload content to any MediaWiki server anywhere in the world.
- Dynamic page naming based on file names containing upload content.
- Multiple wiki Categories can be assigned to pages as the content is uploaded.
- Any wiki user can utilize this script to upload content, does not have to be an administrator.
- Bulk uploading of content from any text based file.
- Wiki page titles automatically generated from filenames during bulk uploads.
- Wiki page titles can be specified by user for single file uploads.
The wikiAutoLoad shell script assumes that the content to be uploaded to the wiki
server is stored in files on the local system; each wiki page is stored in a separate
file. This script requires the
wget command to send files and receive cookies from the wiki server.
Several other scripts are provided that create specific segments of the business continuity wiki structure. The bcupload2wiki_k93 script and the mkbcupload_k93 script contain the business continuity structure discussed in this article. The mkbcupload_k93 script contains the entire business continuity structure and generates the bcupload2wiki_k93 script. The bcupload2wiki_k93 script actually communicates with the wiki server and creates and modifies the pages. Both are provided so the user can modify the business continuity structure to suit their particular needs and requirements, then regenerate the bcupload2wiki_k93 script before any changes are made to the wiki server itself.
For the business continuity category structure for wiki upload, use this script to upload a business continuity category structure to a wiki server, utilizing the wikiAutoLoad script and wget.
The mkbcupload_k93 script generates the business continuity upload 2 wiki script using a list of categories defined within this script. This script can be easily customized to suit your particular needs and requirements.
The drupload2wiki_k93 script and the mkdrupload_k93 script contain the entire disaster recovery structure and generates the drupload2wiki_k93 script. The drupload2wiki_k93 script communicates with the wiki server and creates and modifies the pages. These scripts are provided so you can modify the disaster recovery structure to suit your particular needs and requirements, and then, regenerates the drupload2wiki_k93 script before any changes are made to the wiki server itself.
The drupload2Wiki_k93 script uploads a disaster recovery category structure to a wiki server, utilizing the WikiAutoLoad script and wget.
The mkdrupload_k93 script generates the disaster recovery upload 2 wiki script using a list of categories defined within this script. You can customize this script for your particular needs and requirements.
The ebupload2wiki_k93 script and the mkebupload_k93 script contain the entire e-business structure and generates the ebupload2wiki_k93 script. The ebupload2wiki_k93 script communicates with the wiki server and creates/modifies the pages. Both are provided so you can modify the e-business structure to suit your particular needs and requirements. Then, regenerate the ebupload2wiki_k93 script before any changes are made to the wiki server itself.
The ebupload2wiki_k93 script, e-business category structure for wiki upload, uploads an e-business category structure to a wiki server, utilizing the WikiAutoLoad script and wget.
The following scripts generate various other sections of the wiki structure and can be utilized based on your needs and requirements.
The shupload2Wiki_k93 script uploads a shell script category structure to a wiki server, utilizing the WikiAutoLoad script and wget.
The mkshupload_k93 script generates the shell script upload 2 wiki script using a list of categories defined within this script. You can easily customize this script to suit your particular needs and requirements.
The mkaeupload_k93 script generates the AIX Expert upload 2 wiki script using a list of categories defined within this script. This script can be easily customized by the user to suit their particular needs and requirements.
An example website called AIX Expert has been built from the business continuity wiki structures described in this article. The overriding concept presented in this article is that AIX technical documentation should never be written; it should be generated automatically from the systems themselves and uploaded on a scheduled basis (hourly, daily, weekly, monthly) to primary and secondary centralized documentation repositories.
The entire purpose of having AIX systems as part of your computing environment is automation (cost savings from multiple aspects). If your AIX administrators are deploying, managing, supporting, maintaining and monitoring the AIX environment on an interactive basis, then there is no point in having an AIX environment. If the previous statement is true of your AIX environment, then one of the following needs to happen;
- Replace your current administrators with actual AIX administrators (apparently your administrators are desktop admins who once googled AIX); or
- Immediately adopt an enterprise wide mentality of business continuity and data center automation. Use this to direct and focus your organization (and AIX administrators) to be compliant with modern data center management methodologies.
Actually, the second option should be the normal way of conducting day-to-day business in every organization.
The automation rule-of-thumb for any AIX (or UNIX®) administrator is this: The first time they perform a task, they should record the commands for future automation. The second time the task is performed the administrator should script the task based on the previously recorded commands. The third time the task is performed, it should be automated and monitored by the administrator, and all future instances of the task being performed should be scheduled and automated.
However, this rule-of-thumb does not apply to documentation, and the reason is because it is already known that documentation tasks will have to be performed on a regular and periodic basis. Therefore, generating the documentation from each system should be part of the initial system deployment and continued for the entire life cycle of the system.
As part of automating any task, a process should include steps to generate its own documentation, or it should be written to a standard that enables a documentation generator to create documentation from the process.
Realistically, complete automated documentation is probably not achievable, but it should be the goal. At a minimum, the automation scripts and procedures implemented on each system should be periodically uploaded to a centralized documentation server. This should be done on a regular basis so that when the scripts are changed, the documentation repository reflects those changes in a timely manner. By using a wiki server that is categorized by business continuity concepts, it provides a better chance the documentation will have a business continuity structure associated with it.
- The AIX Expert website was created using the concepts and scripts described in this article.
Get products and technologies
- Shell scripts
- Binary executables
- MediaWiki Software
Dig deeper into AIX and Unix on developerWorks
Experiment with new directions in software development.
Read and subscribe for the best and latest technical info to help you deal with your development challenges.
Software development in the cloud. Register today and get free private projects through 2014.
Evaluate IBM software and solutions, and transform challenges into opportunities.