Neil Perlin presented two workshops on Friday, March 26 in Willow Grove, PA as part of the 2010 STC-Philadelphia Metro Chapter Annual Conference.
I attended the Topic-based and Structured Authoring workshop, a hands-on, constructive workshops that will provide you with knowledge, practice, and new skills.
Topic-based authoring has become a hot topic recently, but the idea has actually been around since ‘91 when Doc-To-Help started the online help revolution. (Or even earlier – ‘65 to be specific, when Bob Horn started InfoMapping.) Yet there’s still a lot of confusion about what it is, how to do it, what tools to use, and what its effects are. And also whether the idea is even as good as it’s cracked up to be…
This hands-on workshop starts with some basic concepts – what topic-based authoring is, its effects on development issues like referencing, continuity, and structured authoring, the tools, with a look at today’s standards – Word and FrameMaker – and newer tools like MadCap’s Blaze, and the effects on long-term development issues like aggregation and single sourcing. The rest of the workshop focuses on hands-on work – taking material written in a traditional “document-style” structure, breaking it down into topic-style chunks with rules of thumb for how to do so, creating navigation between the chunks, tagging the chunks for retrievability, and setting standards for topic-based authoring.
A workshop CD contained 3 files for us to use, a *.css file, a handy Document Spec Template (useful!), and Topic-Based and Structured Authoring – Information Type Definition Form.doc to help us identify the primary information type of our content chunk.
Thoughts to ponder
Consider the Seven (7) Plus or Minus Rule (7+/- rule). Humans can remember about seven things, plus or minus a few.
When crafting your content, links from topics are right there, so the 7+/- rules does not apply. However, do not link directly from a procedure step because you lead the reader away from the task at hand.
Structured content has “structure”: it’s consistent and has signposts for users. However, there are 3 types of structured content around today:
- Visually structured (formatted Normal style, for example)
- Programmatically structured (using styles)
- Programmatically and visually structured (templates)
The programmatically + visually structured content is best, although there is no enforcement for practical, consistent use (no semantic tagging that classifies information).
Benefits to topic-based authoring:
- Ownership – one owner per chunk of content
- More CMS integratable
- Better future-proofed (able to reuse for future uses that do not exist yet)
- New outputs appear quickly
Accelerated pace of change for content tools: development and adoption. How do we know what tool to choose? Price for incorrect choice might be expensive (time, effort, lost productivity).
Topic-based authoring = TBA
Structured authoring = SA
TBA and SA seem to be solution for a clear set of content challenges and problems.
TBA and SA don’t solve all problems. Plan before you go. Avoid paralysis by analysis.
So… you want to use TBA and SA
STOP, ask these questions to assess the risks and challenges:
- Do we have information types now?
- Does anyone know what they are?
- Do content providers follow them? (if not, are they amenable to using them? do they need training?)
- Any tool changes required by providers?
- Any practice barriers to change?
Legacy content history
Try to gather information about content history: when and how created, culture at that time. This information can help convert and transform into TBA and SA.