Transitional text plays no role in most technical content

Transitional text (between sections, for example) is not required in techincal writing and complicates reusability.

Background

Johnson (14 Widespread Myths about Technical Writing) refers to (Myths about technical writing) which references Hackos (2006) who says “I contend that transitional text plays no role in most technical manuals, being an unneeded relict of a book-oriented design.” She suggests that such organizing text (to summarize and introduce) is neither necessary nor helpful in online content because online content is not read linearly and there are typically other organizing elements in the content to serve the same function. In the context of DITA and modular content, such text assume a context that might not always apply.

Survival tips

Hackos and the comments that follow her post suggest a pragmatic approach: If the content works without the text, leave it out. If it helps to have the text, keep it in.

Commentary

This is more of a style issue than a myth. In general, if content still works after you take something out (e.g. transitional text), leave it out. The point of the myth is to say that online content is not a book so book-oriented customs and “best practices” don’t always apply.

Mentions

• 14 Widespread Myths about Technical Writing
• Myths about technical writing

References

• Hackos, J. (2006). Do We Really Need All that Glue? published in dita.xml.org (http://dita.xml.org). Taken on Aug. 28, 2017 from http://dita.xml.org/do-we-really-need-all-glue published Aug. 29, 2006.