On March 17, I attended this full-day (7 hours) pre-conference workshop on topic-based authoring (TBA). Linda Urban has been working with topics for about 20 years now. Add her experience in teaching technical writing, and I can imagine few people better qualified to present this topic.
It’s an excellent, well-structured workshop which
- Provides an overview of TBA, its concepts and its principles
- Shows what TBA is, what it’s not, and why it’s useful
- Defines topics and their elements, as well as information types
- Discussed how to write effective topics
- Demonstrates best practices to introduce TBA and pitfalls when converting legacy contents
- Includes many practical exercises, such as identifying, chunking, and connecting topics into coherent documentation
I took away several insights that came from Linda’s practical experience or from the discussions, e.g.,
- Improve usability when converting legacy contents, don’t convert stuff that nobody uses.
- When in doubt what to cover in topics, start by documenting the users’ “happy path”.
- Connecting beats chunking: Completeness and usability of TBA become apparent when you connect your topics.
- While TBA affords faster reviews, don’t forget to review (or eliminate) older topics.
Several participants actually knew about TBA already: Some had come for a reality check and some because they need to teach TBA to their team. And it seemed everybody got a lot out of it! I think this is a great 101 course workshop since it’s tool-agnostic and focused on the principles and processes.
I understand that this was not an “exclusive engagement”, so if you missed it or need an on-site workshop, contact Linda. (I get nothing for this endorsement, I just think it’s a really good course… 🙂 )