by Susan Earley
What commonly-known and commonly pervasive community entities specialize in data management? Libraries. Every community either has or is near a community library. However, in most organizations, the practice of organizing documents is left to anyone who either shows an interest or insufficient protest. Given the importance of documentation in IT shops, and its use as a source of meta-data, there’s a good case for instituting library science processes and procedures to keep the IT documentation organized and useful.
In every organization, there seems to be a plethora of documents covering the systems and projects, all of inconsistent format, scope, content, quality, and location. Effort to find documentation for a prior project ranges from simple (for some recent projects) to complex (for older projects) to impossible. This documentation contains vital data about how our systems are installed, configured, and operate. In most organizations, there is no organized central repository for this data. Some of this data would also qualify as Meta-data. Most of this data is unstructured in Word, Excel, PowerPoint, Visio, and other digital document formats.
Innumerable projects have seen defects occur due to the lack of this information being available to requirements analysts, designers, developers, and testers, costing both time and effort to a) recreate the information where it doesn’t exist, and b) recover from defects due to assumptions that could have been proven false given the proper documents.
How we got here
We fail to treat system documentation as data. We are constantly working on changing our documentation standards. Teams are independently working on standard forms and formats. No effort is set aside for retrofitting older existing documentation to current standards, so while we may have a ‘current’ standard, that standard may become obsolete and be replaced with another standard, adding complexity to the effort to understand the existing documentation. (This is the same issue that electronic storage faces for data management – making sure old archives are either converted to new technology, or old technology is kept around long after its lifecycle ends, to ensure access to the archival information.)
There is no consistent overall ‘best practices’ organization to this effort, and any effort relies on the documentation creation and organization skills of the IT staff involved (who may not have the skills and/or training necessary) to create and organize. As more documentation is created, in varying formats, the complexity of finding proper, up-to-date, and accurate documentation for systems that are being modified becomes more difficult.
Why change?
Just as we want to organize our customer data for ease of use, we need to be able to organize our system and project documentation to become a more effective IT organization, reduce analysis, requirement, and design effort, and aid in preventing defects.
The end state envisioned is that all of IT would have access to this library of documentation, to enable copy/paste of pertinent info into requirements, analysis, design, development, and test documentation, which will reduce research and document writing work during those phases, and enable faster time-to-market for IT projects. Complete documentation would also reduce errors due to unknown factors, also enabling faster time-to-market for IT projects.
I believe that all of IT should be driving this effort. This problem is pervasive, affecting all parts of IS. People hired for their design, coding, or testing skills are expected to also be expert writers and librarians, without the necessary training and experience. The impacts to different teams within IT may range from negligible to considerable, yet all teams would see some improvement.
What it looks like
Through some quick research on the internet, I have found that a few companies are using Librarians (who are trained in methods of documentation and document management) to manage their documentation repositories. I have also heard that the trend in Library Science is to include electronic documentation management training in order to cross over into this field. It also seems that the job market for librarians is soft, so there should be many qualified candidates to choose from in the market, should this be taken to the next step. There would also be a need for a repository system, and tools to maintain a central repository, of which there are several on the market.
It should be possible to determine someone to focus on this effort, create document organization standards, obtain an appropriate document management tool, start with a specific area of documentation, and set about organizing a specific subset of our documentation as a pilot, measuring the impact to research effort for existing and upcoming projects. Then build on that success with other areas of documentation iteratively.
Since the last phase of the project documentation process in the SDLC (build) would be used by the initial phase of other projects (analysis), in order to reap the best benefit first, technical documentation should be the first documentation set to be incorporated into any new technical library repository.
How to start
First, define the job function and position in the organization that would focus on collecting and organizing the existing documentation. Once that is accomplished, analyze the organization’s current documentation landscape, and determine the most appropriate tools and standards. Then develop an implementation plan for determining and creating consistent documentation standards for documents going forward, and migration plans for existing (and still relevant) documentation to the new repository using the new standards.
For additional reading:
An article highlighting benefits of Technical Librarian
http://articles.techrepublic.com.com/5100-10878-6124017.html
Dept of Labor definition of Librarian, note especially the eighth and ninth paragraphs under NATURE OF THE WORK.
http://www.bls.gov/oco/ocos068.htm
photo credit: Renaud Camus
