Tip

Linux admin fixes: Lack of documentation

This tip originally appeared on SearchEnterpriseLinux.com, a sister site of SearchSMB.com.


Lack of cohesive documentation is one of IT managers' most common complaints about Linux, says Peter Harrison, who canvassed many

    Requires Free Membership to View

IT pros while writing The Linux Quick Fix Notebook, a new book from Prentice Hall PTR. In this quick-fix tip, Harrison offers advice that can help IT managers fill the Linux information gap. - Editor

IT managers and their staff tell me that they are under constant pressure to reduce costs, improve performance and deliver results quickly. They frequently don't have a lot of time to do a lot of research before embarking on projects. Additionally, there is frequently insufficient time to get adequate training so the Internet and books are heavily used resources.

The problem admins identified is that there are two broad categories of books and a mishmash of information on the Internet.

Encyclopedic Linux books focus too much on introductory topics such as Linux installation, user administration and file management while providing only light coverage of intermediate and advanced topics. Specialist texts often focus on a particular application to the exclusion of other related ones. The Internet has a wealth of information, but it is often highly detailed or vague. There are few one-stop Web sites that cover commonly-encountered Linux issues.

To counter these frustrations, IT personnel often jot down the solutions to their problems on scraps of paper, and if pressed, they will create internal documentation outlining the most commonly used processes within the organization. The former solution isn't scalable, and the latter one takes time to implement.

Start your own documentation project

Issues related to documentation can be addressed by investing in a small library, staff training and the maintenance of an in-house documentation project that focuses on repetitive-company related processes.

When writing about on-the-job tasks, follow a few simple guidelines:

  • Get your IT staff most familiar with the topic to write the first draft of your documents.
  • Go over the documentation with them to make sure it is understandable and flows properly.
  • Have as much sample screen output, or screen shots as possible in text or graphical form.
  • If you have the luxury of a technical writer, hand it over to them for final polishing. The document should be economical with words. Bullet-point form is good.

Documentation is not fun, and it will be hard to get it done properly, but once done, it pays off handsomely. Good documentation…

  • helps to resolve problems quickly;
  • improves morale by spreading the knowledge around;
  • reduces the dependency on subject matter experts for the most trivial tasks; and
  • allows staff to expand their careers, as they won't be tied to supporting a legacy system about which only they have expertise.

Document storage is also an important factor to consider. Printed manuals may be appropriate in a formalized training environment, but electronic documents are frequently more practical to use. This is because of their smaller storage requirements and the ease with which they can be indexed and searched especially when they are accessed via a Web portal in a universally accepted format, such as HTML.


Do you have comments on this tip? Let us know.


This was first published in June 2005

There are Comments. Add yours.

 
TIP: Want to include a code block in your comment? Use <pre> or <code> tags around the desired text. Ex: <code>insert code</code>

REGISTER or login:

Forgot Password?
By submitting you agree to receive email from TechTarget and its partners. If you reside outside of the United States, you consent to having your personal data transferred to and processed in the United States. Privacy
Sort by: OldestNewest

Forgot Password?

No problem! Submit your e-mail address below. We'll send you an email containing your password.

Your password has been sent to:

Disclaimer: Our Tips Exchange is a forum for you to share technical advice and expertise with your peers and to learn from other enterprise IT professionals. TechTarget provides the infrastructure to facilitate this sharing of information. However, we cannot guarantee the accuracy or validity of the material submitted. You agree that your use of the Ask The Expert services and your reliance on any questions, answers, information or other materials received through this Web site is at your own risk.