Martin Documentation

From Wikipedia, the free encyclopedia
Jump to: navigation, search

Martin Documentation is a documentation methodology designed to provide different information about procedures depending on the audience and use of the document while also providing for procedure development, procedure change and error correction in both procedures and their documentation.

Martin Documentation is intended both for documenting existing procedures and developing new ones.

Implementation of a Martin Documentation project[edit]

Creating and maintaining Martin Documentation is a procedure and can therefore itself be described with Martin Documentation. The first step in implementing a Martin system is to create Martin documents describing the documentation procedures for the particular organization, i.e. workgroup, factory or corporation. However, Martin Documentation recognizes that different procedures require different amounts and types of documentation at different times, that procedures and their documentation change over time and procedures are created outside of formal frameworks. This means that the procedures for creating the procedures and documentation can be very vague and informal at first, e.g. a copy of this article, and then grow as needed with the rest of the project.

Framework[edit]

Martin Documentation recognizes that procedures are created outside of any formal framework through the creativity of the human mind therefore a document describing a procedure can be a note scribbled on a piece of paper, pre-existing documentation from before the Martin Documentation project was started, documentation from a vendor or any other source and the Martin system allows all documents to be included within its framework.

The Martin framework consists of a set of documents for each procedure. The documents for a procedure can be thought of as a tree structure with a trunk, branches and roots. The same information is repeated in different places in the tree which suggests storing the information in a database where software can create documents as needed by gathering details from stored information and provide hyperlinks from one document to another.

Trunk documents and branches[edit]

Documents making up the trunk formally describe the procedure as it should be performed. Documents at the top of the trunk, the thinner documents, describe the procedure in the least detail while documents at the bottom, the thicker documents, have the most detail. Each document in a trunk contains all the information in the document above it. The trunk can be set up like an expanding outline and stored electronically with the different levels of documents being created from the outline as needed. It may also be desirable to create documents that one could consider to be on the same level but have slightly different details e.g. for the same procedure performed with different equipment or at a different location.

Suggested trunk levels[edit]

  • indexing information- e.g. document number, catalog number, department number, project code, etc. (Some of this may be hidden when printing thicker documents, be considered ancillary documents for the main document number or all of the indexing information may be ancillary to the title.)
  • procedure title and possibly text descriptions of the indexing information
  • short descriptions of the steps to be used by a trained person as a reminder and possibly headers for the steps described in the document below. This should include procedures for preventing and detecting common errors.
  • detailed description of each step in the process. (This level or a variation of this level will most likely be used as the formal documentation when needed.)
  • detailed description of each step with notes and explanations about particular situations and links to procedures for correcting errors.
  • above with explanations about why certain steps are done a particular way to be used as a guide when developing changes to procedures or creating a procedure on the fly for correcting an error.

Branches[edit]

Each document on the trunk may be associated with ancillary documents which can be represented in a database as links to other information including other procedure documents.

Root documents[edit]

Root documents can be pretty much anything having to do with the procedure. Often it will contain historical documents, outside sources and documents about infrequent situations. All procedures start out as root documents even if they only exist in the mind. Most procedures will become part of the Martin system by inclusion as a root document. This allows a procedure to be included by simply giving it a title and links to other documents in the system. Computer databases allow root documents to be stored electronically or may provide information for finding physical documents.

Principles of Martin Documentation[edit]

Inclusion[edit]

Procedures and changes to procedures originate from outside the system and must be put into the Martin system before they are lost. People should be encouraged to record any ideas about a procedure in any form so that at the very least it may be included as a root document and available for future development. All procedures start out as a procedure title or number attached to a root document. Some root documents may also be linked as ancillary documents to trunk documents. Procedures for including root documents should not be so complex as to discourage their inclusion and should instead be designed to encourage their inclusion.

For many procedures the root document may be all that is required for a very long time and an effort to create thicker trunk documents should not be considered a necessity.

Expansion[edit]

If it is necessary to create or change a trunk document, the root documents, existing trunk documents and existing ancillary documents are available as a resource. It might be helpful to create a procedure document describing how to make the decision to expand the documentation of a procedure. At what level a trunk document is created should depend on the nature of the need and the existing documentation for the particular procedure.

Error prevention, correction and detection[edit]

Procedures should include prevention, detection and correction of errors. Procedures for correcting errors should not encourage people to leave errors uncorrected.

History[edit]

Martin Documentation was inspired by the naturally occurring evolution of software documentation in free software projects. Originally described by Jeffrey John Martin.