What is documentation
We produce many documents as part of our roles within ICS. Not all of these documents should be considered documentation. Documentation is any content that includes information that should be shared with other team members to allow them to learn and function within their given role. Documentation may also include templates of documents, emails, and other assets, but does not include the assets created from these templates. For example, we have an SOW template which should be include in our documentation. However, the individual SOWs produced for each project are NOT considered documentation.
Working Documents
Documents that are frequently updated by one or more people and are typical what could be considered "working documents." These documents do not contain information that would be relavent to training a new team member, but are often used for thing like planning or running agendas. This documents may transition to documentation over time, but typically will remain as a working document for it's entire lifecycle.
These documents are necessary for the day-to-day function of the team, but should not be included in documentation. However, information about these documents should be included in our documentation. Things like the purpose, owner, and location of the document(s) should be easy to find and understand quickly if the document is relavent to the reader.
Working documents will eventually become either documentation or a historical document. Once the project has ended, the team (or team member) should review the documents produced by during the project and determine what can be archived as a "historical document", what can be transitioned into the shared documentation, and what can be discarded.
Working Document Examples
- Current project planning documents
- Current project notes and datasets
- Team planning documents
Historical Documents
This type of document can be hard to categorize, but truly historical documents should not be included in documentation. In the example about SOWs cited above, we explained the difference between the SOW template being "documentation", while the actual SOW was not. This is because an SOW issued to a client is a historical document.
The subtle difference between a template and a document produced by the template is an important one. Templates are considered documentation because they are useful for team members as a reference while performing their role. The document produced from the template is only helpful when historical information is needed specific to that project and that document. This eliminates the document from being considered documentation.
The template and information about the documents produced by the template should be included in our documentation. For example, in the section of documentation that describes or provides the template, there should information about when to use the template, how to produce a document from the template, and where documents made from the template are stored.
SOW Template Example
Blurb about SOWs, when, and how to use the template...
Documents produced by this template should be stored in the Project SOWs folder on box. If you are looking for an SOW for a specific project, you can find the project folder or file here: SOW Projects Folder Link
Historical Document Examples
- Project SOWs
- Signed DUAs and other contracts
- Planning documents from closed projects