Red Hat Bugzilla – Bug 809680
RFE: New topic type: Note
Last modified: 2014-10-26 21:12:23 EDT
A Note topic is injected into another topic.
Its root element is <note>.
The purpose of this topic is to enable the injection of "Tech Preview" "Subject to Change" etc, notes into topics.
I've been using two different patterns to deal with this so far:
1. Creating the note as a reference topic and manually placing in Content Specs next to topics that need annotation
2. Directly injecting non-reusable text into topics
The note is meta-information about the topic, but when it's implemented using strategy (1) it is not encapsulated with the topic content in any way. It could be separated by chunking, and it is not reused when the topic is reused - necessitating lots of manual wiring, and loss of the meta-information when someone else uses the topic.
When it's implemented as (2) the note content needs to be maintained and translated in multiple places.
Perhaps useful functionality would be the ability to "tag" a topic with a note, and have the system inject the note topic, rather than having to code it into the topic content xml.
That seems like a better separation of content and meta-information.
Also to think about: when a topic is Tech Preview in one product, and not Tech Preview in another (such as an upstream book).
In this case the meta-data about the topic is project- or output- specific.
Here is a use case where it would have been nice to have this feature:
I needed to report a field in a tab in a UI. There were several places I could put the report of that field, but I put it in the first place. If I need to add it to the other places, I will have to open each of the topics associated with those places and manually add the information to each of the topics. That seems like it's the opposite of what topic-based authoring is supposed to cause writers to do.