Chapter 1 Summary - Writing Software Documentation (Haupt)
I begin my review of Chapter 1 with a criticism. Too much focus is placed on the writing of software end user documentation. In my career I have found that writing software documentation involves a great deal of documentation that is much more complex. These projects include writing functional requirements, end use cases, trace matrices, documenting source code, and writing application-specific technical reference manuals.
This chapter assumes that the writer will be focusing on end user manuals - assuming a near complete lack of technical expertise among the potential readers of the manual. In fact, the authors state that they are only considering three types of documentation, user manuals, reference manuals, and tutorials. Totally ignored is the massive amount of documentation generated during the software development process - a process in which the involvement of a technical writer is invaluable.
I also take exception to the author's list of "Tools of Software Documentation". He focuses on graphics, grammar, page layout, and document design. While necessary, these elements are hardly complete. I would add proficiency in database administration tools such as SQL Enterprise Manager, coding (Java, C#, .Net, C++, and Visual Studio, etc.), and LAMP (Linux, Apache, MySQL, and PHP). For a technical writer to truly be effective he/she needs to possess true technical abilities in addition to the requisite writing ability.
Finally, one last criticism. The book focuses on page layout. In a world of XML data repositories and compound documents this focus has become irrelevant. Authors now concentrate on the text and not the formatting of the text. Automatic formatting is accomplished on the back end by page rendering engines such as Antenna House or RenderX. The whole point of XML is to separate the physical formatting of a document from the logical structure of the document. Additionally, the purpose of Darwin Information Typing Architecture (DITA) is to separate the structure of the document from the content of the document. The entire industry is moving to a model in which physical formatting is automated and delivered at the moment of publishing - not at the time of document authoring.
This chapter assumes that the writer will be focusing on end user manuals - assuming a near complete lack of technical expertise among the potential readers of the manual. In fact, the authors state that they are only considering three types of documentation, user manuals, reference manuals, and tutorials. Totally ignored is the massive amount of documentation generated during the software development process - a process in which the involvement of a technical writer is invaluable.
I also take exception to the author's list of "Tools of Software Documentation". He focuses on graphics, grammar, page layout, and document design. While necessary, these elements are hardly complete. I would add proficiency in database administration tools such as SQL Enterprise Manager, coding (Java, C#, .Net, C++, and Visual Studio, etc.), and LAMP (Linux, Apache, MySQL, and PHP). For a technical writer to truly be effective he/she needs to possess true technical abilities in addition to the requisite writing ability.
Finally, one last criticism. The book focuses on page layout. In a world of XML data repositories and compound documents this focus has become irrelevant. Authors now concentrate on the text and not the formatting of the text. Automatic formatting is accomplished on the back end by page rendering engines such as Antenna House or RenderX. The whole point of XML is to separate the physical formatting of a document from the logical structure of the document. Additionally, the purpose of Darwin Information Typing Architecture (DITA) is to separate the structure of the document from the content of the document. The entire industry is moving to a model in which physical formatting is automated and delivered at the moment of publishing - not at the time of document authoring.
posted by Carl Haupt | 9:31 AM
8 Comments:
This textbook has a 2003 copyright date, but I too question how thorough and relevant it is to the realities of 2007 tech writing. Carl, you know a lot more about writing software documentation than I do, so I accept your criticisms of this book. The writing I'm currently involved with probably falls more in line with what Barker discusses - reference manuals and tutorials. It's simpler and more basic.
I confess I've had this textbook before and wasn't that crazy about it then. It's not any easier reading it now. (In fact, last year I started a message to Allyn & Bacon documenting the editing errors I found...but never sent it.)
At least the book will generate some good discussion!
This comment has been removed by a blog administrator.
I can see where your criticisms are coming from Carl, the book does seem to play to the tutorial, reference, and procedural end-documents.
Anne brings up the books publishing date and how it may be out of date with the current writings of technical communicators. I feel that Barker still has some important things to say to those who are in various stages of their tech comm careers. It teaches the newer ones the basics while reminding the established ones what the basic types of documentation are. Essentially, the three types mentioned above can cover a vast array of documentation and we need to keep this in mind at all times to guide our efforts. Topical? Perhaps not. Required? Absolutely.
I'm in the same boat as Becky. Carl, your terminology and knowledge is far too advanced for me to fully comprehend, so I'll take your word for it.
I also must admit I'm in the same boat as Anne with regards to this textbook. I used it for a previous class, and thought it was much harder to read than it needed to be. But, I'm hoping after a year of further schooling I'll be able to get more out of it this time around.
One thing I want to add to the discussion is this: I wonder if there will be an opposition between this book and our 'Guidelines for Developing Instructions' text. Barker promotes a task-oriented approach, while GDI claims their text will not promote task-analysis.
Obviously, they are not word-for-word the opposite, but it may make for two vastly different viewpoints. I for one would look forward to being given several different ways to look at the same project, so I hope these two books can provide some sort of point-counterpoint relationship.
I hope that we all don't have to be "technogeeks" to be able to produce effective documentaion. Because you are doing the job for which we are training, perhaps you have much more insight into what really goes on and what we really need to know. Please continue to inform us about the "real world!"
I think it's great to read something that seems authentic and really enjoy your criticism of the text. I would much rather sit and talk with someone from the "real world" than try to decipher what is important to know and what isn't. I wonder if it's fair to say that the text is outdated or is it just simply inaccurate? I would be interested to know. I guess I'm not familiar with all of the things that you mentioned in your blog, but like I said-it just sounds more pure and believable coming from a fellow classmate who has experience in the industry. I look forward to reading your blogs in the future.
I've seen the silo problem in group projects from previous classes.
I'm fairly inexperienced out in the "field" so I really don't know how out of date the text is, sadly.
Post a Comment
<< Home