Declarative profiling

[mbakeranalecta]

I am finding a lot of what I would call declarative profiling. That is, content that is profiled not because it is being marked for inclusion or exclusion when the file is included in a particular product manual, but simply because it is only true of a particular product.

For instance, in preferences-diff-dirs.dita, five separate blocks of text, which together comprised the entire body of the topic, were profiled editor, author, developer. In one case, the profiled block was nested inside another profiled block.

The topicref that included this file is itself profiled editor, author, developer, so these nested profiling attributes had no effect on the output -- they simply cluttered up the source and made it harder to edit and maintain.

In cases where a product might subsequently include this functionality, and that product was added to the profiling of the topicref, the topic would not have displayed properly. There would only have been a title with no body at all.

Personally, I am in favor of declarative profiling as a general principle, but it is not the DITA way of doing things, so I am removing this profiling where I see it, and where it is easy to see the effect. Unfortunately, it is not always easy to tell when profiling in the topic has no effect.

My recommendation is:

• Make sure that the profiling we include inline is not simply duplicating the profiling at the topicref or mapref level.
• Remove any purely declarative profiling we see.

Comments?

[georgebina]

Sure, we can remove profiling when the topic level profiling does not make any difference if we take into account the topicref profiling attributes.
We have the same situation for a mapref versus a map - see the Author Developer Guide - maybe we should remove the profiling info from the map also in this case, as we have the same profiling on the mapref.

[raducoravu]

   We have the same situation for a mapref versus a map - see the Author Developer Guide - maybe we should remove the profiling info from the map also in this case, as we have the same profiling on the mapref.

As long as the map is not published by itself in some case. Is it?

[georgebina]

When we get the SDK documentation from the Author Developer Guide we use product=sdk.

[mbakeranalecta]

As far as a map being published by itself is concerned,I think we need a system in which there are maps playing well defined roles. I have already begun to do this as I break things down into sub-maps. I use and chapter. prefix for maps that define chapters, a section. prefix for chapters that define sections, and an eppo. prefix for maps that define presentation-level topics.

If we do this consistently then any separate publication would require a separate publication-level map, so you would not get situations where a map might be published independently in one case and as part of something larger in another case.

This approach will help us to ensure that profiling is applied consistently at the right level.

As far as maps go, the introduction of key has greatly expanded the role of maps. They are not just a way to build a TOC anymore. They are metadata labels. As we move to key-based addressing for xrefs and transclusions (and I believe we should move to exclusively key-based addressing for these things) we are going to need more maps, and we are going to need to manage them in a systematic way so that we can clearly understand the consequences of any changes we make in content or organization.

[georgebina]

The plan will be to use the UserGuide.ditamap with the product=sdk condition to obtain the complete SDK documentation and do not transform the AuthorDeveloperGuide and the PluginsDeveloprGuide, etc. separately to get parts of the SDK documentation.