For experienced MadCap Flare users, this post may be a familiar trip down memory lane. However, the issue addressed here is quite relevant for new Flare users and those considering the move to topic-based authoring.

Boundaries between print and web are fading

The majority of us have realized that it is not efficient to write for print output first, do some clever tricks with conditions to reduce content and undergo a post-publishing process to obtain HTML5 output. Although there used to be a stark contrast between the densities of text in PDF vs. an HTML5 version of documentation, word count is gradually becoming similar in both targets. Rich tools for embedding progressive disclosure in Flare projects for online output empower you to present your documentation in HTML5 and other online formats without overwhelming readers with too much text density.

With topic-based authoring, relatively short and “to the point” chunks of information are ideal, even for print. Since we are creating output for smaller screens, and many customers may be reading text while on their feet, we need to get our technical documentation point across quickly.

Letting go of the past

Since customer preferences in consuming technical information have changed so radically, many of us must make an effort to let go of the past, in terms of visualizing paper pages while writing.

In the last decade, several themes and catch-phrases have cropped up in webinars and conferences, such as:

  • Every page is page one
  • Less is more
  • Capture your reader’s attention in less than 45 seconds
  • etc. etc. etc.

While all of this makes sense, those of us who have recently arrived from traditional, print-dominated authoring solutions may not have put these maxims into practice. Why? In PDF or print, “every page is page one” is not quite as evident as in HTML output. Authoring through the lens of the printed page is the barrier that many people new to topic-based authoring must overcome.

Why does “page-oriented” text density persist?

Although Flare is an ideal environment for topic-based authoring, once we start writing, some of us still create text density more appropriate for out-of-date paper publications. Why?

  • “It’s important! I have to tell them everything.”
  • Many of us come from a Book/Chapter model in products like FrameMaker® or Word. A chapter was our “container” and we tended to create more text density with fewer breaks.
  • When writing for PDF-only in a “page display” environment, we had a subconscious urge to fill all that white space with text. When working in page-based projects, we avoided huge gaps of white space at the end of chapters or sections. The page-sized “container” was often too deep for the topic at hand.
  • In a traditional publishing environment, we had no tools for progressive disclosure, like drop-down text and expanding text. This gave us fewer choices for online navigation and prioritizing critical information near the top of the “page.”
  • Legacy documents that we convert into Flare projects are sometimes heavy on paragraphs and short on headings. Many times, one “topic” from a PDF-oriented legacy file contains information appropriate for 4 or 5 unique topics.
  • Writing for PDF or paper in traditional page-oriented format created a visual viewpoint for content that is more narrative than topic-oriented.

How to get started

Occasionally, we need to write initial portions of a DRAFT as a narrative flow. Our writers’ brains may need to just get thoughts “on paper” without thinking of topics during the birth of our text.

When this is the case, you could use Word for your first draft with sensible use of H1, H2 and H3 headings. When you import the document into Flare you will have a logical progression of topics.

When a narrative flow is necessary to get your ideas on your authoring screen, you can also create one long topic in Flare, then “chunk” it out when you have finalized H1 topic headings.

The rewards of topic-based authoring

Due to Flare’s elegant user interface and assortment of power tools, topic-based authoring will soon become second nature. Flare assists you by providing a default XML Editor that does not closely resemble printed output. If your style sheets and targets are set up to address HTML5 and PDF, you can choose the PDF medium in the XML Editor to get a better sense of page-based formatting, when appropriate.

Flare also rewards you by allowing you to create style sheets and targets that grant a true “single source authoring” environment for print and web experience.

Once you have successfully let go of the “page lens” for viewing content created in topic-based authoring, there is no turning back.