Documenting product development

I mentioned in my last article of 2007, that as a technical writer you can expect to be asked for several kinds of documentation within your organization.

Recently I started to structure the product requirements and product specifications of my customer's products. The intended audience consists of the product manager and product architects on the one hand and the developers on the other hand. The goal of my work is to create a knowledge bank in which the audience can see both the product requirements and the relevant specifications next to each other.







At this moment there are two types of documents:
  1. A functional requirements document: This is a 27 pages long Word document, including some illustrations. It has a thematical structure. This document is written and edited by two product architects.

  2. Component design documents: These are detailed functional and technical descriptions of parts of the product, first written by developers and then edited by two functional designers. The component design documents have a structure that is based on the functionality of the specified component. Every document has a different structure. One of the requirements is that these documents remain in Word and that the audience will always get the latest version of these documents.

The main problem with these documents is, that it is impossible to make a match between the functional requirements and the component design. The structure of the documents is completely different.

Approach

  • I decided to first make a model of the product, using a composition model.
  • Next step would be to add the content of the product requirements to the model
  • Then I would add links to the relevant component design documents.
  • And finally I would make a knowledge bank of it with navigation.

I use the Be Informed Productsuite here because it offers support for the product modelling, the adding of content and on the fly creation of a knowledge bank (web application)

Making a composition model of the product


This model was not based on any of the existing documents. Instead I analyzed the structure of the product and made a series of models out of that. I used small models and connected them to each other with reference concepts. A reference concept is a concept in another model that you refer to.

The advantage of using smaller models is, that they are much easier to maintain.

Comments

Post a Comment

Popular posts from this blog

Using the Golden Circle Model in your resume and LinkedIn profile

Image
The last three years I worked as a (senior) business consultant and information architect at software company Be Informed in Apeldoorn, the Netherlands. We worked on an amazing product, a ground breaking model-driven business process platform. And my job was to explain the possibilities of this platform to various audiences. The Be Free program, which I launched in September 2013 was a marketing campaign that targeted on making a wider group of people familiar with the product. The campaign was a great success and I had the feeling that I was really helping people in proving their ideas to their customers and managers. But the interaction was on-line and from a distance, never close enough to really understand their business goals and issues.  The sudden end of my contract with Be Informed, forced me to rethink my professional goals and ambitions. What do I really want? Do I want to be a product marketer, focused on 'pushing' a product? Or do I want to be a business cons
Read more

Improve Product and Brand engagement through smart documentation - A White Paper about the challenge of creating user-centric documentation

Image
For most product manufacturers, delivering adequate documentation is a constant challenge. The increasing complexity of products and the stricter regulations for product documentation often lead to extensive documentation sets with 500+ pages manuals on-line or in print. The question is: how effective is all this documentation? Smart, user-centric documentation Users can be overwhelmed by long, jargon-loaded user manuals, and frustrated by a lack of clear answers. When customers don’t find a solution, blame inevitably falls on the product and the company. Bad documentation - incomplete, unclear, out of date - creates a negative engagement with products and brands. Figure 1. Smarter documentation asks users what they need to know Smart documentation leads users to success and satisfaction. These are the users who share their positive experience with family and friends, and convince them to become customers in turn. Using semantic technology, we can create the smart document
Read more

Laying the foundation for an effective article

Image
In this series of articles you can follow my process in writing a new article on Robotics. In the  first episode  I explained my approach towards writing, the  second article  focussed on setting the goal, choosing an audience and finding the right approach. Now that we have a clear vision on goal, audience and approach, it is time to start setting up the structure. Writing requires a structured approach Writing is all about structuring your thoughts. And although this is a process that most of us do in a more implicit way, it sometimes helps - and is actually best practice - to write down your structure on a very high level. The goal of my article is to change the opinion of the reader towards accepting Robotics as a something that brings value to a business and motivates employees, rather than being limited to reducing FTE. So the structure of my article should be build up around the motives used to build up this case. As I want my article to be short and sharp, I don't
Read more