Documentation

I’ve written a lot of different kinds of documentation in my career, and I list and describe them here. Some types of documentation are formal, as in manuals written for various phases of a project, but others will be more ad hoc, like punch lists used in place of formal tracking tools.

To be thorough I’m going to include some document types that may not usually be thought of as documentation per se, though they are still relevant types of documents, and they can include a lot of technical material.

Individual documents can (and should!) be generated for most of the phases of my business analysis framework, depending on the complexity and scope of the effort.

Sometimes the documentation is in the form of a word processing file and sometimes it is spread over many locations in a content management system like Confluence, WordPress, or some kind of Wiki page. In Agile projects a lot of the documentation, at least during the build phase of a project, will be hosted piecemeal in a distributed software system like Jira or Rally. There may be a lot of overlap, but every situation is unique, so let’s just jump on in.

  • User Manual: This one is kind of obvious. However, a system can have many different types of users, so individual manuals (or at least sections) can be written for users in every end user role as well as installers, maintainers, user managers, and so on. I often tried to include a story walkthough in my user manuals. Rather than just describing what every field and control on every screen of every program did and meant, and how every input and output artifact was to be processed, conditioned, and interpreted, I provided a narrative describing how a user would exercise most of the features in a logical order.
  • Sales Proposal / Project Bid: These might not seem like normal kinds of documentation but these packages can be large, complex, and highly technical. I’ve prepared process and instrumentation drawings, heat and material balances, test descriptions, process guides, personnel information, budgets, company teaming agreements, schedules, and other materials for inclusion in sales and bid packages.
  • Technical Manual: These documents can include details on almost anything, but they are usually meant to contain information of a highly technical nature. Descriptions of collected data, assumptions, equations, references, techniques, code, and other specifications are just some examples of what can be included in documents with this name. You could buy the Technical Reference Manual for the original IBM PC, which contained some detailed specs but was mostly famous for providing the complete BIOS listing in assembly language. I’ve written technical manuals that described how all the data was collected or otherwise derived, how it was conditioned and processed, and then how it was used in complex systems. I sometimes managed and serially updated these documents over a period of years. In one case I built a system to automate the calculation of initial values, internal coefficients, listing of source materials, and output of governing equations (with equation numbers), variable listings, and value tables.
  • Procedural Manual: This document describes how activities that support an effort are to be carried out. For example, I wrote a Data Collection Manual to describe how my company’s data collectors were supposed to collect, process, and incorporate data, from discovery and data collection trips to dozens of customer sites, as well as what and how much data needed to be collected. This kind of manual could then be delivered to the customer so they could use it to maintain and update the delivered system on their own. This was for a program whose purpose was to build a tool to generate models for every land border crossing for Canada or Mexico, and then collect data for the individual models.
  • Policy Guide / Business Rules: These lists of directives tend to describe organizational process requirements in terms of how certain decisions are made, the time periods allowed to complete certain activities, duties certain people must perform, and things that cannot be done. Policies may be imposed by outside agencies in the form of customer requirements or government laws and regulations.
  • Data Dictionary: These documents can describe all relevant data items, their provenance, their methods of collection, their meaning, their acceptable (ranges of) values, and so on. I have always included this information in other documents.
  • Glossary of Terms: This document describes the specialized terms of art for a project, system, practice, organization, or profession. I think I may have contributed to a standalone document of this type for one project, but I have often inclluded this kind of information in other documents.
  • Intended Use Statement: I originally saw this described in a Navy specification for performing full-scope VV&A on simulations. Its purpose was to describe how a simulation was to be used to support a particular type of planning and scheduling analysis. I’ve appropriated this language to describe the purpose of a project involving a system that is to be automated, constructed, simulated, reengineered, upgraded, or otherwise improved.
  • Conceptual Model: This document describes what’s happening in a system or process that is going to be automated, constructed, simulated, reengineered, upgraded, or otherwise improved. This type of document is often referred to as describing the As-Is state of a system.
  • Requirements Document: This document can describe several things. One is what the system needs to be able to do at the end of the project. These items are referred to as functions requirements. Another thing that can be described is the qualities a system needs to have, usually in the form of -ilities (e.g., reliability, flexibility, maintainability, understandability, usability, configurability, modularity, etc.), and those are referred to as non-functional requirements. Procedural requirements, which are requirements for how the project, effort, or engagement, should be carried out, are probably best considered a subclass of non-functional requirements. I’ve written and managed requirements in multiple contexts and dealt with requirements written by others in multiple contexts as well. This type of document is often referred to as describing the To-Be state of a system. In particular I think of requirements as an abstract description of the To-Be state.
  • Design Document: This document may describe the components, layout, configuration, operations, tools, interfaces, and methods that will comprise the solution. It can define what the solution will be and how it is to be implemented. There are as many ways to create design documents as there are projects to be completed. The details don’t always matter if everyone understands what is being proposed. There should be a balance between detail and flexibility depending on the type, scale, and complexity of the effort. A manufacturing line including specific equipment meant to provide a specific, contractually defined level of production should be specified up front and should probably be implemented using a Waterfall methodology. A software system whose details must be partially defined on the fly should likely be specified piecemeal using an Agile strategy. I’ve produced many items that were intended to serve as design documents and they were presented at varying levels of abstraction. A lot of communication in this area is taken for granted. Be sure to review and seek approval from the customer before proceeding. I think of this type of document as representing a more concrete description of the To-Be state of a system.
  • Implementation Document: This item could be a plan for how the implementation is to be accomplished (this was also discussed as possibly being part of the design document). This could include instructions for ongoing governance (e.g., change control procedures, communication and permissions, and so on). It could also be a record how how the implementation has been carried out. It can be in the form of an updatable text document or in the form of a data system of some kind, along the lines of a Jira, Rally, or VersionOne.
  • Test Document: This item can describe test procedures and also progress attained, in which case it can also function as a checklist. I’ve seen some pretty comprehensive test plans in my career. A good formal test plan should exercise and verify every possible function and capability of a system. All appropriate artifacts and operations should be validated as well, but that often involves expert judgment and that can be difficult or impossible to automate.
  • Accreditation Documents: These documents could include plans for how accreditation is to be carried out (plan) and how it was carried out and the resulting recommendation (report). These artifacts can bookend similar documents describing how V&V is to be and was completed. One possible description of how this could work is here.
  • Requirements Traceability Matrix: This artifact serves as a unified checklist that crosslinks every item in every project phase (intended use, conceptual model, requirements, design, implementation, and test and acceptance in my framework) both forward to the next phase and back to the previous phase. Every element should be linked in both directions (except for the initial and final phases). If all items in all phases are accepted as complete by the customer then work may be regarded as finished for the entire project’s identified and agreed-upon intended uses and requirements. I’ve only used this formally on one large, very formal, two-year project where my company was part of a team acting as an independent agent for the V&V of a deterministic simulation tool the Navy was adopting to manage large fleets of its aircraft. Since I learned about this and earned by CBAP certification I’ve become a huge fan and advocate its use in every effort of sufficient scale to warrant it, and will use it informally on smaller efforts.
  • Statement of Findings: This document may be generated to relay the findings of any kind of investigation one may conduct. This is intended to apply more to troubleshooting or forensic investigations than normal discovery efforts. I’ve prepared a few such reports for different situations over the years.
  • Status Report: These can be issued at various intervals and include varying amounts of information. Their contents may or may not be formally defined. They are usually targeted to defined distribution lists (which sometimes consist of just one manager or customer representative). I’ve written a ton of periodic and ad hoc status reports over the years. Automated tracking systems of various types can generated custom formatted periodic and ad hoc reports of activity as well.
  • Field Report: These documents describe discoveries and accomplishments at remote locations. In my experience these have almost always been customer sites. There can be a large overlap between these and other report types in this list.
  • Recommendations: These items come in many forms and can be produced as the result of a formal investigation or audit (I wrote a couple of these for customers in the paper industry as a young process engineer) or as the result of an informal observation (I’ve proposed numerous internal process improvements to companies I’ve worked for, with this being one recent example).
  • Punch List: These are usually informal to-do lists of tasks to be accomplished. They are usually generated and worked off near the end of projects where formal management techniques and tracking tools aren’t being used. They can be for strictly internal use or reviewed at intervals with the customer. I saw a lot of these when I visited turnkey pulping lines my company was installing for customers in the paper industry and I reviewed them in morning meetings with some customers in the steel industry, for whom I was building and installing supervisory furnace control systems.
  • Specifications: These are often standard descriptions of individual pieces of physical equipment, but they can also describe systems of physical components or software.
  • Request for Proposal / Request for Quote: Organizations in some fields (especially government and heavy industry) will advertise that they need to have specific work performed or items provided and potential vendors will respond with proposals describing how they will provide the requested goods and services. The issuing organizations may provide guidelines for how the response package must for formatted, and these specifications can be extremely long and complex. I’ve contributed artifacts to many bid packages in private industry and have worked on some insanely complex and formal packages for the federal government and the City of New York.
  • User Stories: User stories are one type of artifact that can be created to define requirements in Agile and Scrum projects. They can be written from the point of view of a human user, a piece of hardware, an automated process, or an external system. They often (but not always) take the form, “As a (type of user), I want to (perform some action), so I can (achieve some outcome).” On some projects user stories are the main or even only way that requirements are specified and tracked.
  • Contracts: Contracts can describe what is to be delivered and also the process by which the work is to be completed. It is generally appropriate to use a Waterfall methodology in cases where final deliverables are described up front in great detail and Agile methodologies where final deliverables are specified in a more open-ended way. Waterfall and Agile techniques need not be viewed as totally different and opposed. I feel they should be seen as usable on a hybrid, continuum basis, as I describe here. I’ve had to understand, manage to, and fulfill the terms of customer contracts of varying complexity for most of my career. I’ve even helped to draft sections of contracts related to my role and areas of expertise.

So that’s what I’ve done over the years. What kinds of documentation have you written that I didn’t include?

This entry was posted in Tools and methods and tagged , , , , . Bookmark the permalink.

Leave a Reply