Tuesday February 12, 2008
Tuesday February 12, 2008
The Evolution of Technical Writing
The last few months, I have had the opportunity to work on technical writing assignments using unstructured Framemaker and DITA. My experiences on both kinds of projects have provided profound insights and prompted several questions.
What are the skills a technical writer must have? Obviously, he / she should be able to present information in a cogent and concise manner with the target audience in mind. With today's ephemeral technologies, the writer now needs to think about how to structure content that lends itself to reuse.
REUSE
I use the word “reuse” in the broad sense of the term....how does one take content originally developed for Product A and modify it to discuss Product B, with minimal effort. In my mind, I see this being possible only if the content is somewhat modularly structured, making it possible to pull out relevant areas and reuse elsewhere.
OBJECT ORIENTATION
Perhaps it is my background as a software engineer with an emphasis on Object Oriented Programming. I have a tendency to organize content into small logical chunks and look at content as a tree with branches and leaves. In the 1960s, unstructured programming, emblematic of the “jump” or “goto” statements, led to unwieldy programs, as the complexity of software increased. It was replaced by structured programming which had a more top down approach and modularized functionality, making it easy to maintain. Object Oriented Programming further organized and grouped similar functionality together.
TECHNICAL WRITING – COMING OF AGE
With software being complex and fluid, software development tools, technologies, and paradigms have evolved to keep pace and provide some sanity to the software developer. Has the field of technical writing seen a parallel evolution? Is content being broken up and modularized with an aim to easily rework and reuse? Emerging paradigms like DITA are providing the platform to enable the evolution. Structured formats like DITA, DocBook etc. force the writer to organize information into small, logical, well structured chunks. These well known formats enable the development of content that has a uniform look and feel, and gives the audience a sense of control and direction.
TRANSFORMATION OF THE TECHNICAL WRITER
Software engineers have had to keep abreast of technologies and constantly undergo training in the latest tools and technologies. The Technical Writer for the most part, has not had to deal with the shifting sands of time in terms of the tools used to author content. Adobe Framemaker ruled in the writing community for a long time. HTML provided a way to make the content come alive. With the advent of structured formats and multiple delivery channels, technical writing has become more than just about describing software.
Writers now need to practice “structured thinking” and understand the schema of nested document structures, build tools and processes. The writer's realm has now expanded from just describing software to iterative content model design, development and publication similar to the environment of a software developer.
Does that seem like overkill for technical publications? I don't think so. In my opinion, "the document development life cycle should roughly parallel the software development life cycle".
AAAAH, NEW TECHNOLOGY!
So what does all this mean? Can a writer take to structured, topic-based thinking like a fish to water? Are the tools available to facilitate the transformation? There are new tools that do simplify the task of authoring DITA based content via WYSIWYG editors and so on. But they have their limitations. But are these tools going to stay this way for ever? When I first started developing software in Java in the mid 1990s, even major Java editors were flaky. Later versions of these proprietary tools and other IDEs like Eclipse and NetBeans improved tremendously, with support built in for code completion, refactoring and enhanced debugging support. I am glad developers did not give up on Java early on.
I find parallels to DITA in this aspect. DITA being a nascent standard, has a dearth of good, user friendly, inexpensive tools. However, if as a writing community, we are convinced that DITA is a truly viable standard, it is a matter of time before better tools emerge.
For a writer to be successful in this new world, training in the tools and technologies is imperative. Lack of support leads to hurdles in adoption and expansion. With a comprehensive tool belt and a solid plan, a writer can accomplish almost anything.
Posted Feb 12, 2008
Posted at 02:34PM Feb 12, 2008 by Sowmya Kannan in Sun | Comments[1]
It seems to me that it's not technical writing that has evolved in the past few months but rather your understanding of it.
As a professional technical writer, I can tell you that technical writing at Sun "came of age" in, oh, I would say about 1996, when the Solaris writing groups moved from unstructured FrameMaker to SGML in the form of the Solbook DTD, which is derived from Docbook. So, for well over a decade, technical writers at Sun have been practicing “structured thinking” and understanding the schema of nested document structures, build tools, and processes.
The move from FrameMaker to Solbook also provided the opportunity for the Solaris system administration writers to launch the process of iterative content model design that they are still following today.
I can also tell you that perhaps the most important skill for a technical writer is the ability to look at technology from a user's point of view while working in the environment where the technology is developed. In my experience, most people who are not professional technical writers, especially programmers, fall into the trap of thinking that technical writing is about "describing software". In fact, there's a huge difference between describing how a product works and explaining how to make it work.
Posted by Paul Davies on February 14, 2008 at 08:49 AM PST #