Or: Is Structured Authoring Necessary At All And Worth The Setup Costs?
[This text is an edited aggregation of the following messages from October 14th and 15th 2003 (German version): http://groups.yahoo.com/group/wwp-users/message/19234, 19236, 19239, 19245, 19248, and 19253. The discussion at first was whether RoboHelp for FrameMaker (RHFM) may become a replacement for WebWorks Publisher (WWP) as a conversion tool for single-source publishing based on Adobe FrameMaker (FM) documents. Then:]
Michael Müller-Hillebrand:
[In my opinion] working with structured documents is the only way to guarantee the necessary technical quality of documents to allow error-free conversion to other media.
David Knopf:
I couldn’t agree more. We have been slowly but steadily moving most all of our clients away from unstructured FrameMaker and toward a structured authoring environment. Many of our customers are very satisfied users of the WebWorks Help format, and they of course stick with WebWorks. For those producing more generic HTML or even compiled HTML Help, XML/XSL is a very compelling solution.
Sean Brierley:
The problem with structure is the investment… you can do much of the same with an unstructured FM approach and WWP, and have been able to do so for quite a while.
David Knopf:
Not really. WebWorks does its thing equally well whether you use Unstructured or Structured FrameMaker. But there are many significant and valuable things you cannot do as long as you continue unstructured authoring, including especially
(1) establishing and enforcing structure rules that guarantee documents are properly, consistently, and correctly structured and guarantee that all content elements are properly tagged (with the corollary benefit that WebWorks conversions are guaranteed to run trouble-free every time);
(2) exporting and importing XML, which can then be shared with other content authors using other XML-compliant tools or transformed using XSL to other formats;
(3) tracking and managing metadata for documents and the elements they comprise; and
(4) integrating effectively with CM/KM systems to improve content reusability.
Admittedly, these benefits are of more limited value in a one- or two-writer shop. However, for larger groups — and there are many — this is becoming the name of the game, if not the game itself.
[Next, John Frazzini raised his voice to comment on David's points about the advantages of structured documents. For ease of reading the answers are interleaved with each other.]
John Frazzini:
Hmmm… I agree with David’s list of advantages for structured documents, but, I, like Sean, am still unconvinced this is all completely necessary and worth the setup cost. True, I’ve been sold on the single-sourcing solution and that has similar setup costs, but structure-enforced documents seem like a big pain to me. Specifically…
David:
Well … I seldom disagree with John, but…
(1) establishing and enforcing structure rules that guarantee documents are properly, consistently, and correctly structured and guarantee that all content elements are properly tagged (with the corollary benefit that WebWorks conversions are guaranteed to run trouble-free every time);
John:
I find that a well-designed template (and a very large stick) solve this problem nicely. Even in a 20+ person group, as long as someone wields the stick, and shows people how to properly use the template (FM and WWP template), you can get away without an SGML kind of solution.
David:
In a group of 20+ writers, I have found this approach generally works poorly. First of all, many writers do not want to, and therefore do not, follow the template. Even the best-intentioned writers do create format overrides. And the stick wielder (and the developmental editor and production editor) have to devote time to correcting errant documents and errant writers — time that could otherwise be devoted to creating or improving content. In a structured authoring environment, 90%+ of the stick wielding is done automatically by FrameMaker. This results in increased productivity in every environment I’ve seen.
John:
One might argue that a well designed template and a big stick is the same thing as enforcing structure with SGML/XML, but the difference is there’s some room for creativity in applying the template when you’ve got a variety of types of documents that you’ve got to produce.
David:
Well, there is a philosophical difference here. There are certain kinds of creativity that I do not want writers to apply. For example,
I don’t want them to creatively place Heading3′s directly after Heading1s with no intervening Heading2s;
I don’t want writers creatively using a single Heading2 under a Heading1;
I don’t want writers creatively deciding it’s perfectly all right for bulleted lists to include only one list item;
I don’t want writers creatively deciding that lists do not need to be preceded by an introductory paragraph;
I don’t want writers creatively forgetting to include figure captions where they are required;
I don’t want writers creatively omitting the TableContinuation variable in table titles.
We can quibble about whether this particular set of rules is “right” or “wrong,” and I would by no means assert that it’s right for all documents or all environments. They’re just examples. My point is that, using a structured template, you can enforce rules like these in such a way that authors are reminded to create valid structures and receive validation errors when they do not. There is no need to rely on an editor, stick wielder, or production person to address these errors. This, in my opinion, is A Good Thing(tm).
John:
That is, as opposed to spelling out everything with schemas, give people a set of building blocks, tell them how to use the blocks, also give them a set of examples of properly formatted documents, then let them play.
David:
Most of my clients do not want their writers to play. They want them to produce the best possible content in the least possible amount of time. Structured authoring by no means ensures that this will happen, but it certainly helps.
John:
It’s like the difference between old-style Lego(tm) and new-style Lego sets. I guess I’m just old-school.
(2) exporting and importing XML, which can then be shared with other content authors using other XML-compliant tools or transformed using XSL to other formats;
John:
This, I think, is the only real advantage of using a structured approach. I’ve yet to see, however, an XML-compliant tool that provided me with better output than a well-designed book.
David:
Well… FrameMaker is an XML-compliant tool that produces great books! I have clients now in which some content authors are using high-end tools like Epic, others are using XMetal, and the pub[lication]s group is all FrameMaker. By defining and using a common DTD, everyone can participate in content authoring using their tool of choice (or the tool they are required to use by management edict). Books are always produced in FrameMaker — either from native Frame documents or by importing XML instances created in other environments into FrameMaker for assembly and production.
John:
There are applications where small bits of text can be better spit out by an XML system and give you good output, but from a cognitive point of view, there are far more applications that require you to design a learning experience for the reader.
David:
I don’t see any conflict between structured authoring and designing a learning experience for the reader.
John:
I think the people who really jump on this bandwagon are selling short the skills of the technical communicator. Going this road really leads to homogenized text that anyone can produce and doesn’t really meet a lot of people’s needs (it’s kind of like the TV network approach to script-writing–writing by committee, vs. the old way of carefully crafting a narrative that people can follow). Sure, this way may save you money in production in the long run, but whose needs are you really serving?
David:
Actually, in my experience, rigorously applying document type definitions and structure rules typically results in better, not worse, content, measured in terms of how well it meets the needs of the reader and user. There is no question that good technical communicators can produce excellent content without structured authoring. There is some question that all technical communicators across an enterprise can accomplish the same thing.
John:
From the transformation point of view, WebWorks can transform your unstructured docs into just about anything, given the well-formed template in point (1) above, so this is less of an issue.
(3) tracking and managing metadata for documents and the elements they comprise;
John:
I’m not really sure why this would be necessary. If you’ve got metadata, sure, there’s a need to track it. But, the structured approach requires metadata, and therefore creates the need. With the approach in point (1), you don’t really have much need to track your metadata.
David:
If you’re writing one book — or five books for that matter — the question of metadata is probably of low importance. If you are an enterprise creating technical documents for hundreds of different products and product versions, metadata makes it substantially easier to identify, locate, and reuse content that already exists, thereby reducing the need to constantly reinvent the wheel. Metadata also enables dynamic assembly of content based on specific user or customer requests.
(4) integrating effectively with CM/KM systems to improve content reusability.
John:
Again, this is an advantage, but due to point (2), I’d refute its general usefulness.
David:
And I’d refute your refutation in much the same way. CM/KM is irrelevant in small shops. It’s of enormous value in large enterprises.
Admittedly, these benefits are of more limited value in a one- or two-writer shop. However, for larger groups — and there are many — this is becoming the name of the game, if not the game itself.
John:
I’d say it’s not the number of writers, but rather the kind of information you’re presenting.
David:
I think both are a factor. Certainly, the type of information is relevant. If you are a publisher of fiction or poetry, to carry the example ad absurdum, structure will give you no value. For technical publications and training materials, the value can be very high. I think the total size of the content authoring group is a factor. With fewer than 6 authors, you can reasonably enforce consistency and structure and the like “the old fashioned way.” When you have dozens of authors in several locations on several continents, it becomes orders of magnitude more difficult to accomplish that goal without structure.
John:
If you’ve got thousands of discrete pieces of information (reference-type stuff), structure gives you some huge advantages (in terms of spitting out small chunks people are looking for using XSL kinds of tools). If you’re trying to instruct people on how to do something, of course structure is important, but flexibility is equally important.
David:
It depends. Some kinds of flexibility are good. Some kinds are bad. The flexibility to violate the basic rules that an organization has chosen to impose on its publications is bad.
[After a few moments John Frazzini wrote (again interleaved with David's answers):]
John:
Shockingly enough David, I think through all of this we actually do agree.
David:
Well, we are pretty close in any case.
John:
I agree there’s a need to create structured content, I agree there’s a need to impose rules, I agree that the greater the volume of documentation and authors, the more need there is for structure and that this generally improves the reader’s experience. I even agree that using a structure-enforced approach will dramatically increase the likelihood that you’ll produce better doc[uments].
I guess the basic point we disagree on is how a tool can help or not help. In the end, it’s the structure creator (or stick wielder in my approach) that makes or breaks whether the system will work.
I think you state my point best:
There is no question that good technical communicators can produce excellent content without structured authoring. There is some question that all technical communicators across an enterprise can accomplish the same thing.
I would expand that to say that there is some question as to whether most organizations that try to implement structure-enforced authoring tools can actually get the benefits they’re looking for.
David:
There is no question that organizations can make big mistakes while adopting structure, just as they can while adopting a single source workflow. All the benefits I have cited, of course, assume a good implementation.
John:
Depending upon who implements the structure, and whether or not that person(s) is a continuing part of the environment (to track and handle changes and enhancements), your mileage may vary.
So, whether you get a person to wield a stick or create a set of DTDs, you’re basically doing the same thing.
David:
Except that once the DTD and EDD have been defined, you do not have to pay them any salary or benefits! And the person who used to spend time doing the stick-wielding recaptures that time and can devote to higher value activities, such as creating or improving content.
John:
If organizations don’t recognize the need for extremely qualified people to perform this task, then whichever approach you choose will fail.
David:
Absolutely. Creating DTDs, EDDs and structure applications is not entry-level work. 
John:
One of the reasons I’ve heard most for choosing a structure-enforced approach is the lower maintenance cost, and that’s the point I’d strongly disagree with. It’s going to cost you more or less the same in terms of people resources and time to maintain a well-designed unstructured FM template as it does to maintain a set of DTDs (because the structure will invariably have to change as new kinds of information are introduced). If you spend less on maintenance, then, you’ll get what you pay for.
David:
My actual experience with this differs. Again assuming a proper implementation, changes to the DTD, EDD, and structure rules should be quite rare. I am working with a client now who last modified their core DTDs in 1996; in other words, there has not been a single structure-related change in 7 years. During those 7 years, content authors have simply created properly structured content. No time or resources have been devoted to correcting tagging errors introduced by authors. The time and dollar savings have been very, very significant.
John:
The one thing you will get is slightly less time correcting problems like David mentions (not following heading structures, not following list rules, etc.). That savings is proportional to the size of the organization, but there’s room for argument about how to quantify this savings.
David:
There is always room for an argument.
The participants
- David Knopf, Knopf Online, San Francisco CA, U.S.A. http://www.knopf.com Consulting & Training for Technical Communicators
- John Frazzini, TIBCO Software Inc., Palo Alto CA, U.S.A. http://www.tibco.com
And as the prompters:
- Michael Müller-Hillebrand, cap studio, Erlangen, Germany http://cap-studio.de
- Sean Brierley, Haestadt Methods, Waterbury CT, U.S.A. http://www.haestad.com