Best way to single-source for version-specific user guide?

[ryan]

If I am single-sourcing files for a user guide across different versions, what is the preferred method to manage the shared content? Should I have one folder of files used as the baseline (e.g., ver4.1), and then make new folders (e.g., ver4.2, ver4.3, etc) and copy over the affected files and modify them individually, and then drag them into a new TOC (e.g., ver4.2, ver4.3, etc)? Or should I create a whole new project for each version sourcing those individual files? I guess what I am asking is does everyone generally manage content at the project level or the TOC level?

[RamonS]

I would manage it at a project level. Often enough you already work on the next version when something needs to be changed for the current version. It is much easier to do that in the designated project. The only disadvantage here is that you would need to make the changes in the current version project as well. That is what developers do in code as well when they branch it for each version. Things that get fixed or changed in the old version need to get fixed or changed in the new version as well.
Keeping everything in the same project and employ things like conditions to select content for versions may work OK as long as the old content never changes in a way as that it won't work with specific versions. Example: You have a set of topics that discuss adding a new record to the system. Fast forward three versions. Now the whole process is changed, the screens look differently, and the workflow is different. If you need the old version you cannot just go ahead and make the changes to the existing topics, you also cannot just remove them. You need to add new topics and make sure that those never ever get included in the old versions and likewise that the old topics never ever get included in the new versions. Add index keywords and links to the mix. And then have that happen not to just one section in the application, but to 25 in the current version, 5 the next version, and 10 then version after that. If you keep all that in one project you will go nuts. The question to ask for this option is: how mature is the application and how likely is a widespread reimplementation of features?

I'd rather do work twice once in a while as in the first option than figure out two years from now what the heck is going on with the bazillion ever so different topics in my project.

[wclass]

We create a whole new project. We have dozens of projects, some updated only once a year and some 3 or 4 times. If you only have a few new topics each version, you might be able to get away with separate folders, but sometimes projects have major restructures. At a project level it is much easier to manage obsolete topics, condition/build tags, CSH mapping, and restructures.

[DocuWil]

What I do is the following:
When a new software product has been created, I start the project withthe name: Product
Then the output file is named:
Product_SV1.0_R1 Software Version 1.0 and Revision 1
My publish directory will be:
My Publish\Product\Product_SV1.0_R1
In this directory I might have subdirectories for doc, webhelp, etc.
When it is published and released I keep my hands off. It's done.

When I notice that something is not written quite well, I change the situation to:
My Publish\Product\Product_SV1.0_R2

And if the software has an update, it starts again:
My Publish\Product\Product_SV1.1_R1
So, after a while it can look like this:

My Publish\Product\Product_SV1.0_R1
My Publish\Product\Product_SV1.0_R2
My Publish\Product\Product_SV1.0_R(n)
My Publish\Product\Product_SV1.1_R1
My Publish\Product\Product_SV1.1_R2
My Publish\Product\Product_SV1.1_R(n)
My Publish\Product\Product_SV1.(n)_R1
My Publish\Product\Product_SV2.0_R1

You get the point I think.

Of course it means that the original topics are overwritten, but is that bad? Not in my case.
I do not say this is a solution. It is a way how I work.

[ryan]

Thanks everyone for the responses. So I think what you are telling me is that using the single sourcing functionality in Flare (conditional text, variables, multiple TOCs, targets, etc.) is OK for small projects or mature software products that aren't expected to change much, but if there are going to be multiple revisions and on-going changes, then this functionality will be too confusing and a bigger headache than its worth in the long run, correct?

And that the best bet is creating entirely new Flare projects based on the previous version with redundant files, correct?

[LTinker68]

I guess it depends on if you use source control or not. And the capabilities of that source control, I guess. My situation is a bit different as I don't have projects that have multiple iterations like you do, so I don't use source control with the help. But if I understand how the software programmers here use source control, the theory is that they can go back and rebuild previous beta or release candidates, if necessary, without having to make a new project in source control for the next iteration. So if you go with RamonS's suggestion that you treat the help the same as software code, then you'd put the help project into source control (except the output) so that you could keep everything in one project in source control but still retain the ability to regenerate previous versions when necessary.

Or, if you don't have source control, you could zip the project (including the output) and name the zip for the release version. If you ever need to go back and rebuild that version, you create a new project at that point and unzip to that project.

[royj]

I use conditions to tag content for the n.x releases, and create a new project for major N.0 releases.

For example, I copied the 3.x project for our 4.0 release and scrubbed out everything but the most current content, and all of the old version conditions. When we started adding features and bug fixes for the 4.1 release, I created a 4.1 condition, plus a 4.0 condition for those cases where I needed to maintain content specific to both versions.

I released updated documentation builds for the 3.x versions (for content errors and bug fixes that impacted the content) up until the 4.1 release, so I didn't have many cases of updating content in two projects.

With the upcoming 4.2 release, it began to get a bit complicated. I had a 4.2 condition, and I already had the 4.1 and 4.0 conditions. But in a few instances, I need to distinguish between things that apply for 4.1 and older versus 4.1 and newer. This is workable, but I don't want to try to maintain more than three versions at a time. (Hopefully, the sales team can convince most of our clients to stay fairly current with the version they use.)

I could stick with just a single condition for each release (4.0, 4.1, 4.2, etc.), and then when I had content that applied for 4.1 and later or earlier, I could simply duplicate it and tag it for each release. But when I created the scheme I'm using, I thought it would be a bit confusing to have two identical chunks of content with different tags. I'm reconsidering that.

FWIW, I'm a single writer creating content for a handful of different projects. My largest project includes 630 topics at last count.

[LTinker68]

I could stick with just a single condition for each release (4.0, 4.1, 4.2, etc.), and then when I had content that applied for 4.1 and later or earlier, I could simply duplicate it and tag it for each release. But when I created the scheme I'm using, I thought it would be a bit confusing to have two identical chunks of content with different tags. I'm reconsidering that.

You might want to make your conditions more generic. For instance, rev0, rev1, rev2, etc. That way when you go from 3.x to 4.0, you don't have to try renaming your 3.1 condition to 4.1 (if that's what you were doing) -- you'd just keep using rev1.

I'm not sure why you'd have two identical chunks of content with different tags. You can apply more than one condition to the same content. So if you have a paragraph that is applicable to 4.1 and 4.2 but not 4.0, then you can apply the 4.1 and 4.2 conditions (or whatever you called them) to that paragraph. That paragraph will not be included when you build 4.0, but will be included when you build 4.1 or 4.2. And if you have a paragraph that is applicable to all versions, then you don't apply any conditional tags. Of course, you'd have to modify the 4.0 target to exclude the 4.1 and 4.2 tags.

[Hobbes]

I use conditions and variables to single source multiple releases and multiple targets for the same project. It works pretty good for the most part, though I will admit it gets complicated after a few releases. I think that is the case with most of the conditional tagging systems I've used.

What I do is create two kinds of conditions for a release. One when something appears for the first time in a release and one when I find out something needs to be taken out for a release. So, say a command gets added in release 2.0, then the condition is "New_in_2.0". Then say that same command is being retired in release 4.0, then the tag is, "Delete_in_4.0". Then when I create the build it is pretty easy to tell what to include/exclude. Then I create a separate target for each software release so I don't have to keep changing my condition selections.

What would be great is if they revamped the conditions interface so I could delete a condition and have the option to either:
- Just remove the tags and leave the text OR
- delete the tags and all the content with those tags.

Also, another tool that I used offered the option to 'baseline' a document. Basically, you select the tags exactly like you would when defining a target, and when you hit the baseline button it eliminated all the tagging--keeping the 'includes' and deleting the 'excludes'. This leaves you with a clean slate to start adding conditions to when things get too messy.

[ryan]

strange I was just typing up a new versioning feature request that would enable you to take a project, select exactly what conditions and variables you wanted to appear, and create a new project with a clean set of files without condition tags. This could be repeated at all major release etc., 5.0, 6.0, 7.0...

[wclass]

Another point to note: remember that if a topic has more than one condition, the includes override the excludes.

Our projects already have conditions for up to 5 output types (webhelp, CHM, Word etc). If I added versioning conditions on top of these then I could get a problem with included conditions overriding the excludes. I think versioning conditions would only work easily if that's all you had. This is another reason why we use project level copies for versions (and maintain in TFS).

(Now I'd like to revamp the conditions interface so that I could explicitly specify my includes and excludes).

[RamonS]

(Now I'd like to revamp the conditions interface so that I could explicitly specify my includes and excludes).

I'm not the conditions expert here, but as far as I know you can explicitly set includes and excludes. The problem only arises when there are no conditions and conditions specify include and exclude for the same content unit. In those cases the include wins.

[wclass]

The problem only arises when there are no conditions and conditions specify include and exclude for the same content unit. In those cases the include wins.

Yep - that's the bit I want to revamp. I've put in a request to let me specify a detailed boolean expression that should let me determine what wins.

For example, I have conditions for 4 or 5 outputs in most of my projects (slightly different versions of the software on different platforms, CHMs, several web helps etc). A single topic might be included in all outputs, or maybe only one or two. Suddenly, the project changes (ever had that happen?) and I need to temporarily exlcude a topic just for this release (so I don't want to delete it). If I assign a temp exclude condition (X), I also have to remove the 4 or 5 valid output conditions else the topic remains in the help. An expression something like "A or B AND NOT X" should exlude a topic even if it has A and X conditions.

Currently, with Includes winning, if you had general output conditions as well as versions you'd have to create some pretty complex conditions to get it to work. I admit, though, that I think that versioning is best done with source control at the project level.

[RamonS]

I agree and see how that will help you out, but what is the default for the condition for conditions in case of collision or non-specification? I think that conditions are getting very complicated as soon as you deal with more than half a dozen. Now adding rules and conditions to those conditions will be the big gun for users to shoot themselves in the foot. I wouldn't want to do Flare support if that features comes out. Maybe it is sufficient to flip the default behaviour so that it is always exclude. That means if you do not specify any conditions you would get zero output.

I'd go with the project level versioning. It may cause some extra work but it strikes me as being easier to manage. I rather would do a dumb task of copy and paste than a tricky task of figuring out why the heck this or that topic slipped through and into release. That said, it all depends on the size of the project and the frequency and scope of changes.