Transitional textMost writers are familiar with narrative writing, in which writers provide transitions that lead a reader from one section to the next (like "Next, we will consider..." or "Having completed the previous tasks,..."). The topic-oriented paradigm incorporated in DITA's design--and implicit in the bookmap model derived from DITA maps--favors a writing style that minimizes the use of such narrative filler between topics. TOC: Architectural_Specification_1.1
[edit] Why topic orientation in writing?Topic-oriented writing is a disciplined approach to writing that emphasizes modularity and reuse of concise units of information--topics. A topic is enough information to fully convey an idea or task in one reading. Well-written topics can be reused in many contexts, as long as writers are careful about a few things.
[edit] Conciseness and appropriatenessReaders who are trying to quickly learn or do something will appreciate if that information is written in a clear pattern that is easy to follow and contains only the information they need to complete that task or grasp a fact. Recipes, encyclopedia entries, car repair procedures--all are informational units that serve up a uniquely focused unit of information that someone has consulted. Typically, anything before or after in the sequence of the document is not of interest--the topic contains everything pertinent to the reason the reader looked up the topic in the first place.
[edit] Locational independenceA well-written topic is reusable in other context if it is "context free," meaning that it can be inserted into a new document without revision of its content to refer to a changed context. This is where the issue of transitional text is perhaps most obvious to writers who are new to topic orientation. Phrases like "As we considered earlier..." or "Now that you have completed the initial step..." are likely to make little sense if a topic is reused in a new context in which those preliminary conditions are different or perhaps no longer existent. A well-written topic will read appropriately in any new context because the writing style within it does not lead the reader outside of the topic.
[edit] Navigational independenceMost HTML web pages are a mixture of both content and navigation, with the contained links representing the web of reading sequences and choices that a reader can make as he or she navigates through a web site. A standalone topic obviously should not have any navigation within it that would need to be changed if the topic were used in a different context. The DITA design supports this separation of navigation from topics through the use of ditamaps, which represent how topics should be organized for particular information deliverables. However, it is still tempting for writers to want to provide links within the content of a topic that allow a reader to consult external resources. DITA does not prohibit such linking, and in fact the markup allows writers to indicate that such links are external--choosing them opens a new browser window rather than taking the reader on a navigational tangent. A well-written DITA topic generally eschews internal linking to other topics within the document set--these are best supported through the map, which allows the topics to be used in any context without internal revision. TOC: Architectural_Specification_1.1 [edit] Transitional text workaroundsTopic orientation does not mean that transitions can't be authored in DITA. The key to providing both locational independence and intentional sequences is the adroit use of DITA markup features.
|
