| 
  • If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.

  • You already know Dokkio is an AI-powered assistant to organize & manage your digital files & messages. Very soon, Dokkio will support Outlook as well as One Drive. Check it out today!

View
 

Topic-Based Authoring

Page history last edited by Dmitry Sokolov 4 years, 6 months ago

Go:

 Visual Taxonomy Links   Hide/Show:

Taxonomy Path

SSS Yet To Be Done.

https://en.wikipedia.org/wiki/Topic-based_authoring 

In technical communication, topic-based authoring is a modular approach to content creation where content is structured around topics that can be mixed and reused in different contexts. It is defined in contrast with book-oriented or narrative content, written in the linear structure of written books.[1]

Topic-based authoring is popular in the technical publications and documentation arenas, as it is especially suitable for technical documentation. Tools supporting this approach typically store content in XHTML or other XML formats and support content reuse, management, and the dynamic assembly of personalized information.

A topic is a discrete piece of content that is about a specific subject, has an identifiable purpose, and does not require external context to understand. Topics can, when written to be independent of one another, be reused in wherever needed.

The Darwin Information Typing Architecture is a standard designed to help authors create topic-based structured content. The standard is managed by the Organization for the Advancement of Structured Information Standards DITA Technical Committee.


 

http://norman.walsh.name/2007/02/05/painting

Topic-oriented authoring

Volume 10, Issue 7; 05 Feb 2007 (modified 08 Oct 2010)

A visual analogy and the importance of good metrics.

I get asked about writing methodologies with some regularity. It often starts as a “DocBook vs. DITA” question, but it's not usually about the spelling of the names between the angle brackets. As I've said before, there's nothing about the DITA methodology that you can't do in DocBook. ¶

Usually it's about topic-oriented writing vs. book-oriented (or what I'm going to call here “narrative”) writing. The subtext is often that the topic-oriented style is better than the narrative style. It'll come as a surprise to very few that I'm not convinced. ¶

The narrative style has been around a long time: ¶

  • It is built on “English 101” principles: introduction, successive exploration of new ideas, review, and reference.
  • “Knowledge units” (topics, sections, chapters) are supported by the units that preceded them.
  • Supports the reader by providing a context for the information presented.
  • Works in print and online.
  • Is not generally amenable to arbitrary reuse.

The topic-oriented style is relatively newer and has different features: ¶

  • It is developed on principles of reuse and minimalism.
  • “Knowledge units” (topics) stand alone.
  • Focuses on documenting tasks, not tools, functions, applications, or systems.
  • Reportedly preferred by “learners” that tend to jump in and “resist detailed systems of instructional steps.”
  • Provides opportunities for the reader to explore in arbitrary directions.
  • Works online; may work in print.
  • Offers the opportunity of arbitrary reuse.

Recently, I was describing to a group of documentation managers, tool writers, and authors how I think these two styles differ and what appear to be their respective strengths and weaknesses. In the course of this discussion, the following analogy occurred to me. ¶

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. ¶

The result may be a little ragged around the edges, and there's no gaurantee that there won't be voids on the canvas, but by and large the result is a complete picture[1]: ¶

Starry Night by Vicent Van Gogh

In the topic-oriented style, the work is divided into topics, or by analogy, the canvas is divided into squares. For this painting, perhaps we'll decide that 60 topics will cover it. ¶

Each square, or topic, is painted in relative isolation. To the extent that the author has the whole topic in view, it too is likely to be relatively complete. ¶

A single square of the painting

In addition to creating individual topics, to save time and effort, similar topics from other paintings can be reused. The final work is achieved by mapping all the topics into a whole: ¶

A checkerboard version of Starry Night by Vincent Van Gogh

Of course, there's nothing that prevents the authors from filling in each topic right to the edges. Nor is there any reason why the result has to have holes in it. But I bet most of you have had an experience similar to this one: ¶

The printer in Deb’s office started to jam. This being a modern piece of hardware, it didn't ship with a printed manual. It didn't even ship with a PDF file of a printed manual. No, instead it shipped with a large topic-oriented help file, er, manual. ¶

After a half-hour or so of searching and following links, I concluded that the manual contained six or seven topics related in one way or another to paper jams. Each of them was two or three sentences long. Each linked to two or more of the others. And none of them actually contained anything very helpful. ¶

So, if the author's metric for success on the question “do we have paper jams covered?” was “Yes, we have seven topics about them,” then I think the metric was a terrible failure. ¶

Similarly, if the author's manager's metric for success on the question “did we produce better documentation faster and cheaper?” was “Yes, we reused seven topics about paper jams without any new writing,” then I think that metric was a terrible failure; not because it wasn't faster and cheaper, but because the resulting documentation was a nearly worthless stack of…bits. ¶

It would be ridiculous for me to suggest that it's impossible to write good topic-oriented documentation, but I think it's a lot harder than it looks. Likewise, it would be narrow-minded of me to suggest that there aren't subjects that lend themselves to a topic-oriented treatment such that the narrative style would be more difficult and expensive to produce. ¶

At the end of the day, I think the really important question is, did the documetation you produced, regardless of the style chosen, actually provide clear, concise, and accurate information for your readers? Your readers probably don't care how many pages you wrote, or how many topics, or how much faster you wrote it, they only care if it answered their questions. ¶


[1]In this case, Starry Night by Vincent Van Gogh. ¶

 


Links  

See also


 

Subcategories

``

Pages

`D

DITA

`I

IVAN

`S

SPFE

 

Pages in Other Languages

 

Forking

 

Categories:

 

 

    Communication stubs

    Comments (0)

    You don't have permission to comment on this page.