Lessons learned from Documenting Product Development
A couple of weeks ago I started really enthusiastic with structuring the product requirements and product specifications of my customer's products. The goal of my work was to create a knowledge bank in which the audience can see both the product requirements and the relevant specifications next to each other. Last week I have finished the knowledge bank and presented it to the product architects. What did I learn from this project?
Don't use your documentation project to restructure the whole organization
First of all: it is impossible to capture the whole world in just one set of models. When you have to think of a documentation solution for a whole organization, it is tempting to restructure everything into one consistent overall structure. The truth is that in an ideal world this would be an excellent solution. In the real world you can't just change everything to get the desired result.
Make a series of models for every single department or organizational unit that has its own documentation structure. Then find the similarities in the models to create one overall integration model to bind the different models.
Define the rules for your models before you start modelling
As a technical writer I am used to first structure my information, before I start writing. The idea of making models of information, is not very different from making a content hierarchy for your documentation. As described in my earlier blog I started with making a composition model for the product range. With only one type of concept and one type of relationship between the concepts, it became very hard to determine on which level of the model you were. So I introduced different types of concepts and relations while I was making the models.
Within a few days the structure became more and more complex and not consistent at all.
This situation can be avoided by first making a design for your models:
Don't use your documentation project to restructure the whole organization
First of all: it is impossible to capture the whole world in just one set of models. When you have to think of a documentation solution for a whole organization, it is tempting to restructure everything into one consistent overall structure. The truth is that in an ideal world this would be an excellent solution. In the real world you can't just change everything to get the desired result.
Make a series of models for every single department or organizational unit that has its own documentation structure. Then find the similarities in the models to create one overall integration model to bind the different models.
Define the rules for your models before you start modelling
As a technical writer I am used to first structure my information, before I start writing. The idea of making models of information, is not very different from making a content hierarchy for your documentation. As described in my earlier blog I started with making a composition model for the product range. With only one type of concept and one type of relationship between the concepts, it became very hard to determine on which level of the model you were. So I introduced different types of concepts and relations while I was making the models.
Within a few days the structure became more and more complex and not consistent at all.
This situation can be avoided by first making a design for your models:
- Describe the concept types used, for instance: "Product", "Product module", "Function" and "Component"
- Define the types of relationships that are allowed between the specific concept types. For instance: "Subclass of" to connect a "Product Module" to a 'Product"
- Create a list a the content types that you want to add per concept type, for instance: "Definition", "Description", "Instruction" and "FAQ".
- Optional: add label types for language versions and additional index entries.
In my next blog I will demonstrate what the effects of these lessons learned were on my project.
Comments