Description
As I attempt to run a full validation on the user manual, I am uncovering a lot of profiling errors, at different levels of the content. These are often revealed by adding a link to a topic which then can't be resolved because the source and destination topics are profiled differently. So far, all these cases have been due to profiling errors, not linking errors.
Some seems to have been there all along, so I am not sure why there were not detected earlier. This is particularly true of the SVNClient and Author SDK profiles.
I think the fundamental issue here is that the current documentation set relies too much on profiling for reuse. It is essentially organized as a single map with profiles used for all reuse, even across completely different products. I think we should move (post 6.1) to an approach based on using different maps for different products rather than profiling a single map.
There are three main reasons why I prefer this approach:
- Conditional processing is inherently complex since the conditions are applied all over the content. It is okay if used locally within a topic where the effect is obvious, and the various profiled elements are side by side with each other. but the cumlative effect of conditions at the map level are harder to trace, especially where they do not exist in parallel because they apply to very different products.
- Profiling places all content in everything by default. That is, if an element is not profiled, it is in everything. It has to be explicitly excluded by profiling it into all the places it should appear. When reuse is done at the map level, everything is out by default and has to be explicitly included to be displayed. This is generally much safer. Omissions are easier to detect than accidental inclusions, and the impact on the reader is less -- an accidental inclusion gives actively misleading information that can kill the users confidence in the docs. Also, working by inclusion rather than exclusion fits better with the author's intention as they write. Thinking about what this topic belongs to is inherently more natural than thinking about everything it does not belong to.
- Profiling does not do a good job of showing its intent. You can generally only see what the result of the profiling is, not what its intent is. (Even with the ability to grey or hide profiled text in the editor, you are still looking at the result, not the intent.) With maps, the intent is immediately visible by looking at the map itself.
We are already laying the groundwork that would support this change by splitting the chapters up into separate maps, and by making separate maps for presentation-level topics. Completing the move to multiple maps should be completed before we make any move to change the profiling. However, I think it is something we should start to think about.