Capturing project knowledge


The planning and documentation phases are thankless tasks. If done well, nobody really notices them. But if you skip them or give them less attention than they deserve, you will end up with a disorganized project that is impossible to maintain. We recommend that the project documentation should, at a minimum, include the following information:

  • Content model explanations and recommended best practices for authors
  • An explanation of all of the important project components, such as the content management system (which one? why chosen? what customizations?), the planned strategy for legacy document conversion, the authoring tools, known limitations, and so on
  • In-depth technical documentation for developers, which will be used to maintain the system
  • Formatting specifications and algorithms

It is also helpful to provide details about the project, background information, and the rationale for various design decisions.

Knowledge transfer is critical to a smooth implementation. Authors need training on the following topics:

  • General authoring concepts (such as writing modular content) and using the designated authoring tool
  • Project rationale
  • Content model
  • Metadata and taxonomy
  • Best practices for authoring

We have found that authors accustomed to an authoring environment with established rules (templates, style guides, and the like) have an easier time making a transition to a new system than less organized groups.

If the staff that built the system will maintain it, little or no developer-level training is necessary. However, if the staff responsible for maintenance is new to the project, extensive training is required. In addition to the information needed by the authors, maintenance staff also needs the following:

  • In-depth understanding of the content model, design decisions, limitations, and trade-offs
  • How to implement and test changes
  • Technical training on the output paths and how to maintain them



Add comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.