Open Documentation

By Sita Bhatt

Open-source software and documentation often lead to the questions if we are talking about:

·          Documentation about open-source software

OR

·          Documentation created using open-source software

This article is about neither of the above. This article is about using the concepts of open-source software to documentation.

Open-source software is a much-preferred option these days – organizations choose it for any of the following reasons:

·          Reduction in running cost

·          Zero marginal cost of scale

·          Better control

·          Ease of maintenance

·          Better traceability

·          Better security

Keeping most of these reasons in mind, the parallel concept of working with “open documentation” sounded extremely appealing to me as a technical writer. To define the term “open documentation”, this documentation should:

·          Be available to other technical publication teams as a valuable starting point

·          Be available without or with a minimum of cost

·          Allow the technical writer to create content without worrying about packaging

·          Be considered usable documentation

Imagine a situation where a software engineer can work with open-source code to create applications of his choice. The following reasons would be his reasons to choose open-source:

·          Unrestricted access to source to modify or run at will

·          Support from fellow users       

·          Stable software

And now imagine this concept as a technical writer; if you could write to support the above causes, what kind of documentation would you write? Certainly documentation that:

·          A technical writer could access freely

·          Was aided with online help

·          Could be used as a building block

·          Could help in creating usable documentation

Adding developer comments to code is a standard that most good software developers use. This standard helps a new developer understand the logic behind the code and continue with development from wherever he chooses to. Such a standard is encouraged by most organizations since legacy applications can be understood and the knowledge stays proprietary.

Applying the same principal to documentation, I thought of the innumerable times when knowledge about the organization’s documentation was not explained due to various reasons. Non-availability of the senior members of the team, earlier management decisions, missing style guides and obsolete guidelines; these were just some examples of how information and knowledge was not conveyed correctly and in required time.

Consider scenarios like these:

·          Source document with comments which were conditional tagged

·          Version control for documentation guidelines and style guides

·          Version control for source documents

·          A read me for every release specific to the documentation set

These are just a few examples of how documentation can be made “open”. The need to have information about information within the information is a trend that is only going to be on the rise. The sooner we, as technical writers, understand this concept of open documentation, the quicker we contribute to business value in an efficient manner.

Sita Bhatt is a Senior Technical Communicator with Infosys.

STC India | Home | Contact Us

Copyright © 2005 India Chapter STC. All rights reserved.