Authoring styles and art
Norm Walsh tackles topic-oriented authoring and makes a comparison to art.
Imagine that instead of authors, we were painters. In the narrative style, a painter (or perhaps a group of painters) begins at one side of the canvas and paints it from beginning to end (from left-to-right and top-to-bottom). They may not paint it in a strictly linear fashion, but the whole canvas (the narrative whole) is always clearly in view.
Interesting point, and he uses an image of a Vincent Van Gogh painting, chopped into unattractive bits to illustrate what goes wrong in topic-oriented authoring. The flow of the picture is lost.
But what if your content more closely resembles something by Mondrian?
Writing useful technical documentation is really, really hard. Using a narrative flow makes it a little easier to ensure that you’ve got the big picture — missing information jumps out at you just as Norm’s chopped-up painting shows.
But topic-based authoring has advantages, too.
Do you need those connections from piece to piece or can individual parts stand on their own?
Are your documents Mondrian or Van Gogh?
I hope for your sake that the product you’re documenting does not resemble Jackson Pollock‘s work.
About the author
Eric
That is a fantastic parallel! In some cases I would imagine documentation could even be considered an entire gallery where some sections are sketches in a series pointing to a larger work and other pieces stand atomically alone. .. Metaphors aside, that is a wonderful example revealing the complexity of documentation and technical writing.
Matt
An entertaining post, but all tongues removed from cheeks, this is really a serious question… My engineers have been after me for years to pull my content out of my presentation (it’s why I moved to authoring with XML-based Flare) and maintain a catalog of content irreducibles that can be called on as needed. Ideally, say they, information should be modular and reusable. I say fine, but without context, gibberish ensues, participles dangle, tenses change, referents and antecedents vanish away like your dad’s best jeans… i.e. chaos! Where’s the balance point? I’d love to know where to say “that’s modular enoo!”
In the end, the more you modularize, the more fiddly stitching you have to do to REUSE the modules to get that “flow” that comes from writing from scratch every time.
Thoughts?
Matt