single-sourcing for 'vertical' versions

[niina_p]

I've gone through Flare's help and this single-sourcing discussion, but I'd still like to consult the forum on how to handle our situation:

We are writing the web help of our product with Flare, and maintain chronological (or 'horizontal') versions of the help in SVN branches. Now we're looking for the optimal way to handle different versions of the help for different versions of the product customized for different customer segments (or 'verticals'). Thus far we haven't been customizing our web help for different audiences. At the moment, using condition tags seems like the most viable option. Given that Flare includes tagged content by default, we would:

• - leave all basic content untagged
  - tag the vertical-specific additional content that should not be included in all versions of the help, and exclude the tag from the basic version target or alternative vertical targets of the help
  - tag the parts of the basic product content that should not be included in the vertical-specific help (for example, features that have been replaced in the vertical), and exclude the tag from the vertical-specific target

However, we've also been considering condition tags for different types of users, along the following lines:

• - tag developer content intended only for internal use, and exclude the tag from all customer targets
  - tag key user content for customer key users, and exclude the tag from the end-user target
  - leave basic end-user content untagged

Our concern is that if we have both vertical-specific and user type-specific content tagged with condition tags, our project tagging will be pretty complicated: basic content would have user type tags alongside vertical tags, and each vertical type would also include a subset of user type tags for that particular vertical. We do not yet have several verticals of the product, but we anticipate this will be the case in the future so we'd like to plan ahead. Do you think we should proceed with our condition tagging plans or consider another option (for example, global linking)?

Thanks for any opinions and advice you can give!

[RamonS]

You drew the right conclusions, after a while the number of conditions and combinations gets rather large and it is only a matter of time until something goes wrong. I'd keep content for internal use only in a separate project and provide it as WebHelp on an Intranet server. As for customer specific content, does that mean different functions in the application or more a difference in look & feel and branding? If the apps are functionally the same I'd keep the descriptions as generic as possible and apply branding through master pages. That way the number of items to condition and maintain is limited.
As for the key user content, you might want to experiment with different projects and merge them as needed. Maybe it is worth going through the trouble of setting this up once.
I hope the revenue numbers match the effort, if not see if you can stop the customizations as they otherwise mean a lot of work for not much gain. Also, how many of the customizations are projected for the next years? After a while the effort to maintain them all may become unsustainable.

[niina_p]

Thanks for the swift reply!

The functionality of the product is different in the 'vertical' versions so it's not just a matter of look and feel.

What could make separating content into different projects somewhat challenging is that the product is quite extensive and at least some of the role-specific content (key users and developers) should be included in just the right topic and place in the documentation. I believe this is not possible if we use different projects and global linking (which is done on the topic-level)? We haven't yet analyzed our documentation in enough detail to determine whether the key user and internal developer content can be extracted to separate topics, and thereby, to separate projects that can be 'global linked'.

I don't have any numbers on the projected customizations, but I'd rather be safe than sorry on the documentation front.

[NorthEast]

Global project linking shouldn't be thought of as an alternative option to conditions; it's a consideration in how you organise your source files, rather than how you build your outputs/targets.

A project import will import files from one project into another, so it's something to think about when you're planning how to organise your source files; i.e. do you just have all your content in one project, or do you have content in separate projects and use project imports to copy in any required files you need.

In your scenario, I think it's unavoidable that you'll have to use conditions to build all of the separate outputs you require. How complicated it gets will depend a lot on how you set up your conditions; so it's wise to carefully plan what conditions are required, and how your content will be organised.

If you have several verticals multiplied by several user types, then presumably that will give you the number of separate outputs/targets.
Also, your application would have to know which of these separate outputs to display for each user.

[i-tietz]

You can also have multiple projects, e.g. admin and user. Those projects share files they have in common. Files which are for admins are in the admin project only, files for users are in the user project. Shared files might have conditional text inside.
You might also split the whole thing up the other way round. If the other split is between big application and small application, you can stuff those into projects and insert the admin and user via conditions only.

If you update one of those shared files the other project will hopefully tell you there's a new version of the file (not working with global project linking but source control). This will make it slightly more controllable. But you still have to be careful using conditions, since the general rule is: include has a higher priority than exclude.

In any case I suggest: Make a table and use specific conditions:

Code: Select all

               GENERAL   SMALL          BIG
ADMIN          ad        ad-sm          ad-b     
USER           us        us-sm          us-b

That might look more complicated but is less error-prone in the long run.

[niina_p]

Thanks again for your answers. Of course from Flare's point of view global project linking isn't an alternative to condition tags. However, from our solution-oriented perspective it is since we're trying to figure out the optimal means to an end. With Flare, customization of content can be done to some extent already on the source file level but also in generating the output. As you already pointed out, the latter (condition tags) will probably be needed which ever solution we end up in. I've gone through Flare's documentation on Global Project Linking to understand how it would work in our scenario. Please correct me if/when I'm wrong:

We'd have one project for the basic product source files and additional projects for the vertical product source files. The vertical product project would contain the content that is additional to or changed from the basic product content. We would create a project import file (.flimpf) in which all content from the basic product project is marked as either included or excluded. The import file would be updated whenever such new content is created that replaces content previously imported from the basic product (the link to the source project is broken and the import selection changed from 'include' to 'exclude').

If it seems more sensible to import some content from the basic product project that contains parts not applicable to a vertical (for example, some selection is not possible in a vertical), we'd use a vertical-specific condition tag. This tag would be excluded in the vertical product project target and included in the basic product project target.

If it seems more sensible to add some vertical-specific content into the basic product project content (for example, a lengthy procedure includes some vertical-specific deviations/steps), we would use a vertical-specific condition tag in the basic product project file and import this content into the vertical product project. We would include the tag in the vertical product project target and exclude the tag in the basic product project target. If the basic product project source files contain larger parts in which a vertical-specific paragraph/line is needed, we would also tag that content, exclude it from the basic product target, and include it in the vertical project target.

Using global project linking seems especially useful when the 'child' project (to which files are imported) contains a considerable amount of content that is different from the 'parent' project. In our case, we do not currently know how much content will be vertical-specific.

i-tietz: You mention shared files through source control. Do you perhaps mean sharing the files through the usual SVN merge-commit workflow or something else?

To give you an idea of the context we're working in: our product is an enterprise resource planning system and our documentation content includes nearly 20 000 files, taking up over 100MB (size on disk). At this point, the vertical customization is something that must be done and the role-based division is more of a nice-to-have.

[NorthEast]

Firstly, I would suggest you actually try out your solution in a test project on a small scale; you'll probably get a better idea of the benefits/limitations of whatever solution you're planning.

I don't completely follow your solution; but I'm not sure how project imports make this any easier than having all the content in one project. You still appear to need the same number of conditions for your verticals. Also, bear in mind splitting topics into separate project will also add some limitations - e.g. if you want links/xrefs between topics that are in different projects.

The vertical product project would contain the content that is additional to or changed from the basic product content.

How would you handle topics in your vertical that have changed from the basic version? For example, you have a topic in your basic version, and in the vertical it has an extra few lines. It sounds like you would have a separate copy of the topic in both projects. Suppose you want to change the text in the basic version, doesn't that mean you have to make the same change in both files? (As you can't re-import the basic file that you changed in the vertical.)

[niina_p]

I'm setting up the test projects as we speak The reason I posted the questions was to find out if you well-versed propellerheads could see and suggest the most suitable solutions in our situation already before we start trying out all the potential single-sourcing capabilities of Flare. Since we most likely will not be able to completely separate the vertical-specific content from the basic product content, I suppose the benefit of global project linking is lost and it is indeed a more viable solution to stick to condition tags - especially if cross-referencing or hyperlinking to the imported content is not possible. If I'm not mistaken, we can leave the bulk of content (the content that is shared for all versions of the product/documentation) untagged?

How would you handle topics in your vertical that have changed from the basic version? For example, you have a topic in your basic version, and in the vertical it has an extra few lines. It sounds like you would have a separate copy of the topic in both projects. Suppose you want to change the text in the basic version, doesn't that mean you have to make the same change in both files? (As you can't re-import the basic file that you changed in the vertical.)

According to my idea, this would be handle by not having a separate copy of the file, but using the vertical-specific tag in the basic product content:

If it seems more sensible to add some vertical-specific content into the basic product project content (for example, a lengthy procedure includes some vertical-specific deviations/steps), we would use a vertical-specific condition tag in the basic product project file and import this content into the vertical product project. We would include the tag in the vertical product project target and exclude the tag in the basic product project target.

[NorthEast]

According to my idea, this would be handle by not having a separate copy of the file, but using the vertical-specific tag in the basic product content:

If you need to include vertical content in both your basic and vertical projects, then there's probably not much case for separating out your content and using a project import. You'll be editing some vertical content in the vertical project, and other vertical content in the basic project; which is probably just going to make things harder if anything, especially if you have links between the vertical content in each project.

especially if cross-referencing or hyperlinking to the imported content is not possible

The links/xrefs are only a problem one-way. It's not a problem to link to imported topics from other topics in your current project; but it is a problem to have links from imported topics to other topics in your current project.
The problem is how do you set up a link/xref in your imported project to a topic that doesn't exist in that project?

Generally speaking, you might find project imports will be of less use if:
- You use a lot of conditions at the text-level inside topics.
- Your topics are tightly integrated/linked with each other.

Project imports may be of more use if:
- You mostly use conditions at the topic-level.
- Your imported topics are fairly independent, and are not tightly integrated/linked to other content.

[i-tietz]

This is the structure in our MS VSS DB (Source Control):

structure_in_sourcesafe-db.png

- A, B, C, and D are projects.
- Level 1 contains files that all projects have in common. Only the odd conditional text in those files, mainly for names or file paths.
- Level 2 contains files that at least two projects have in common. Here some more text is conditional.
- Level 3 is in one project only.
- We have one main condition tag set with one condition for each project.
- We also have more condition tag sets for other purposes, e.g. handling a specific sort of list in a few different tasks - they have tiny differences but the main handling is the same. We use snippets that include conditional text and use snippet conditions in the topics for sth like that. Those conditions are neither included nor excluded in targets, but in topics only.
- We have conditions/condition tag sets for new subjects/objects, to keep them out of the output as long as the feature is not part of the application.

- If we had user and admin helps we would also have a condition tag set for the roles - in all projects.

But as I said, the real problem is the logic of includes and excludes: If you have conditional text or topic or folder that has more than one condition, the include overrules the exclude. If I have a new feature I want to exclude from output but also use admin/user conditions on that text the admin/user include in the target will overrule the exclude of the new feature. You gotta have a well-built logical structure of conditions!!

Idea: You could have one project per version - that way you wouldn't need the condition for new features.
You do the selection of this topic in this project, that topic in that project inside the database - not in Flare. You link the one original file to all the projects that contains it too. It means: If you change the file in any project it is part of, all the other projects are informed that there is a new version of the file. In the pic the linked files are those in the black part.

[niina_p]

It does indeed seem that dividing the source files into separate projects and using global project linking will not work for us since referring to the child project from the parent project is not possible. I've tried out condition tags instead in our test project to verify how including and excluding works. You've mentioned the following:

If you have conditional text or topic or folder that has more than one condition, the include overrules the exclude. If I have a new feature I want to exclude from output but also use admin/user conditions on that text the admin/user include in the target will overrule the exclude of the new feature. You gotta have a well-built logical structure of conditions!!

In my tests, when I marked some text in a topic file as excluded and a smaller part inside it as included, the exclude was overruling and the included part did not show at all. The include tag was only dominant when the marked part was exactly the same. Is this how it's supposed to work? (Flare's help has good instructions on how to tag content, but I didn't find detailed descriptions of how the priority of include and exclude is determined.)

As for the control of new features, we actually use different branches in the repository for that and merge-commit updates on, for example, new features to relevant branches only.

[i-tietz]

ah - you're right - that was imprecise ...

You gotta separate conditional text with different conditions from each other. And you're right: Only if the spans are identical the logic works that way.
For texts you have to have the spans side by side not one inside the other. And: Yes, that means redundancies or snippets.

With files and folders it's different: If a folder has an excluding condition and a file inside that folder has an including condition, the file will be included, the rest of the folder won't.

[NorthEast]

Basically, the Include setting is only used when the conditions are applied to exactly the same item - i.e. the same file, HTML tag, TOC item, etc.

If you exclude something, everything inside it is excluded - regardless of any conditions they use.

With files and folders it's different: If a folder has an excluding condition and a file inside that folder has an including condition, the file will be included, the rest of the folder won't.

No, that's wrong - if you exclude a folder then none of the files inside that folder will be included, regardless of what conditions they use.

[i-tietz]

With files and folders it's different: If a folder has an excluding condition and a file inside that folder has an including condition, the file will be included, the rest of the folder won't.

No, that's wrong - if you exclude a folder then none of the files inside that folder will be included, regardless of what conditions they use.

Sorry - No, that's right:

condition_logic.png

I included condition "blue" and excluded condition "red" ...

[lacastle]

With files and folders it's different: If a folder has an excluding condition and a file inside that folder has an including condition, the file will be included, the rest of the folder won't.

No, that's wrong - if you exclude a folder then none of the files inside that folder will be included, regardless of what conditions they use.

Sorry - No, that's right:

condition_logic.png

I included condition "blue" and excluded condition "red" ...

i-tietz is correct. include ALWAYS wins.

[LTinker68]

i-tietz is correct. include ALWAYS wins.

Explicit includes always win (i.e., you checked the Include box in the target). Exclude wins over implicit includes (Include box in target not checked).