Profiling issues

[mbakeranalecta]

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:

1. 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.
2. 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.
3. 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.

[raducoravu]

Hi Mark,

You should perform the validate and check for completness only on the top level map and by adding all the available DITAVAL filter files to the list. I do not get that many errors when doing this on the changes George merged a week ago.

The only kind of errors I obtain are these ones:

             System ID: D:\projects\userguide\DITA\concepts\installation.installer.windows.dita
            Engine name: oXygen
            Severity: error
            Description: Key definition 'executableInstall' not found in the DITA Root Map.Keys are gathered from the root map: UserManual.ditamap.
            Profile: authorEclipse
            Type: Key reference
            Start location: 9:61
            End location: 9:80
            Length: 19

because in the DITA content I'm validating new topics you have created like "eppo.installation.windows.dita" are not profiled do belong only to the standalone distributions, this is probably something you fixed in the GIT repository.
We also have an automated test which runs every night on our internal user manual SVN repository (which for now is updated manually by George from the public GIT repository) and should report such problems.

Profiling makes sense in some way for the author/developer/editor values because the editor is the superset of the author+developer and it contains all topics, then the author and developer each have a subset of referenced topics.
The authorSDK should probably be removed because we are not using it for anything.
The SVN client exists both as a standalone distribution and embedded into Oxygen standalone author/developer/editor.
Also we need to consider that in September we need to release Oxygen 16.1 and the user manual should be in proper order until then.
George will get back in about a week and maybe he'll have his own ideas on this.

[mbakeranalecta]

I was doing the validation with "From all available condition sets" per George's instructions (unless I misunderstood his instructions). In any case, the files are now valid when validated either way.

I agree about profiling author/editor/developer, particularly at the topic level. And we definitely should not make any changes like this before 6.1.

[georgebina]

We need to clarify what we will do with the author SDK condition set but otherwise the user guide should be valid for
author

• developer
• editor
• authorEclipse
• developerEclipse
• editorEclipse
• svnClient

Regards,
George