An Open Framework for Technical Communicators?

In the previous post I mentioned that creating user-oriented documentation requires an understanding of the audience and its tasks and processes. The trick has always been that it is hard to explain the days or weeks spend on audience and task analysis, while it doesn't deliver a visible contribution to our work from the start. There also isn't a real method or framework - that we can refer to - that demands the activities and deliverables that come with an audience and task analysis.

In this area we can learn from ICT Architects, especially when it comes to:
  • Usage of a common and widely accepted framework like DYA or TOGAF
  • Development of standard notation methods, like Archimate for creating models of the different architectural layers of a solution
  • Visibility of all activities and models in the end result.
Standards versus an Open Framework
A fact is that there are standards for documentation, but they are more or less focused on the quality of the end product and not on the process of creating it. In the same way as the Open Group has created a framework for Enterprise Architure, a community of technical communicators - supported by for instance the Society for Technical Communication (STC) or the Institute for Scientific and Technical Communicators (ISTC) - should stand up and define a set of tools, templates and methods for technical communicators, presented as an open framework.
There is absolutely nothing wrong with the current education programs and standards, but what we need is something that bundles all efforts and transforms it into an industry standard. And in my opinion this standard should focus solely on the process of documentation creation instead of on the end product of it.

How do we benefit from such a framework?
Do you get tired of explaining over and over again why you need that audience analysis or why you want to pretest your documentation? Well, as an ICT Architect I only have to say that I have to comply to the TOGAF standards and all discussion about needed analysis and modelling time is gone. So having our framework for technical communication would not only give us a good reference on how to do thing, it will also make it easier to explain why we need activities like audience analysis and pretesting. Not complying to the framework is still a choice, but it will be an explicit one.

What do we need to create such a framework?
Well in fact most of us probably have an idea what should be in it. We have a lot of knowledge, best practices and research data available at for instance the STC and the ISTC. In my opinion the focus should be on bundling and prioritizing the information that we already have, to produce a version 0.1 of our very own Technical Writing Framework. By making use of the international community of technical writers and the possibilities of communities on the internet, we can evolve this method to the technical communicator's equivalent of TOGAF.

How do we give it the status of a real framework for technical communicators?
Well I know it might sound too easy, but in my experience something "new" becomes "common" just by accepting it as the standard and start communicating about it in this way. And yes, we need a website, we need a name for the framework and we need people to spread the news and share their experiences.

I hope this is enough food for thought for now. Don't hesitate to drop your opinion in the comment box or start a discussion.

Next time I will continue my exploration of lessons learned as an ICT Architect. First I will look at the similarities between TOGAF and the process of writing technical documentation and come up with the raw outline of a framework for technical writers. Next I will talk about using modelling techniques - similar to Archimate - that technical communicators could benefit from in the earlier stages of their writing project.

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

Writing effective articles

Image
I am a writer. I have been all my life and I wouldn’t know what to do if I would ever lose this talent. I have been writing about many topics: from welding procedures and high tech greenhouse technology to  software implementations and the use of semantic technology.  Apart from the writing I enjoy digging into these topics and finding out how things really work and what the benefits are of these new technologies or approaches. But is a talent for writing in combination with an interesting topic enough to form the basis for a successful and effective article? Or do we need more? In this series of blog posts I will explore the criteria for a successful article, not necessarily providing you with a fix set of rules but rather focusing on best practices, lessons learned and examples from my own work. On the cover of a magazine One example from my own work. In 2008 I wrote an article called “The Flexible Intranet” about using semantic technology to create smarter Intranet sites...
Read more