Model first, write later

The use of models fits perfectly in the professional approach of creating user documentation:
  1. Define the goal, audience, and context:
    Clearly define the context, goals, and audiences. The design of documentation should be goal-driven—from the user’s point of view. Often, a brown paper or moderation session will help you define these goals and requirements. Involving users in this first step helps them understand the process and gives them an ownership stake in the solution. Create models of the goals, models and other important context factors and discuss them with the involved users.
  2. Analyze processes and activities:
    This is an important step in creating goal-driven documentation and should lead to a model of all relevant processes and activities. Also define the roles of different users within the processes.
     
  3. Create the overall documentation model:
    this phase involves creating an overall structure for the product information, as well as linking this product model to the process and context models. Decide what instruments you want to use to disclose the information: navigation, facetted search, decision trees and/or wizards. Choose navigation if you want your users to be free to browse through the information, facetted search if you want to help them find specific information, and decision trees or wizards to help them make decisions or perform a certain action.
     
  4. Create content:
    The fourth phase involves the creation of content. Create content references in the models to make the content available. Content can be created with multiple tools and in various environments: from a local source editor on a workstation or laptop to a full blown CMS that publishes its content in the cloud. The content can have a multi-level structure, consisting of headers, sub headers and content. There are no limitations in the presentation of illustrations, tables and other graphical elements, although in some cases (depending on the chosen toolset) some adjustments in the style sheets or CSS are required.
     
  5. Test and improve:
    As soon as the first models are finished, testing can start. Testing and improving is a continuous process, where users can be involved from the moment that you start modeling. Because the models present a graphical presentation of the product and its processes within the context, they are perfectly understandable for business users.
Throughout the whole process collaboration and reuse of content and structure  is key. The same models and (parts of) the same content can be used for different purposes and in a different context. Technical communicators, architects, analysts, developers, marketers and business users can all work together on the models and the content, with technical communicators as modelers, writers, testers and architects of the final end result.
 
Possible roles of the technical communicator in the process of creating smart documentation are:
  • Information architect: responsible for the main design, the meta models and overall structure of the documentation. The information architect also monitors the growth of the documentation solution and directs the actions of the entire project team. This would be a role for a senior technical communicator.
  • Modeler: responsible for the models that represent the product and the related processes, users and context. The modeler uses the meta model and overall structure that is provided by the information architect. This is a typical role for a technical communicator with some experience in structuring information.
  • Writer / editor: writing in a model-driven environment is often not an isolated activity, but has a strong relation with the modeling process. The role of writer is therefore often combined with the role of modeler. Novice technical communicators can start in this role and gradually learn how to embed their content into the models. In an optimized situation, other disciplines within an organization will also add content.
  • (Usability) Tester: the role of tester is often underestimated in documentation processes. In a model-driven environment the testing consists of two activities:
    • Verifying the models
    • (Pre-)Testing the user interface of the documentation solution based on user scenarios.
The role of (usability) tester requires a at least some years of experience in technical communication and experience in modeling.
Collaboration is key: multi-disciplinary teams work together on models and content.

Join me at the STC Summit 2013 for an interactive demonstration

As announced earlier, I will demonstrate how we can use semantic technology to create process-driven documentation at the STC Summit 2013 in Atlanta.  I will do this by live modeling with a semantic tool set. As the models in the semantic environment are instantly executable, we can watch the documentation develop, change the models and review the results in a web browser.

When: May 6th, 2:00 pm (EDT)
Where:  Hanover FG, Hyatt Regency Atlanta - Track my session
Level: Advanced

 

Download the white paper

The white paper “Improve Product and Brand engagement through smart documentation” is available for download on: http://info.beinformed.com/stc13 . This white paper will give you some background information for the session. Downloading requires an email address, so I can keep you up-to-date on future developments (there is always an opt-out).

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