Hello all,
I hope this is the correct place to post this. Quick backstory, I recently took a job and inherited multiple projects. The company provides a software platform to approximately 35 clients, with the baseline software being specifically tailored to each client. This includes both additional features and subtraction of baseline features. From what I have seen so far, differences typically apply to either a third of the clients, two thirds, all but one or two, or only to one or two. One project is for the older version of the software, and was worked on by three separate writers, so it's a bit of a mess. The current outputs are wrong for many clients, and after a week of digging in I think this is mainly because of the way the conditional tags have been applied. They are applied inline, on block level, html level, and topic level pretty inconsistently. A lot of topics are conditioned for all except one client (there is one condition tag set that is a list of all of the clients, that is all).
I've been told the old software will not really be updated anymore, as they just launched a new software that will start going to new clients. My predecessor set up the new help project, which is much cleaner, but she set it up the same way as the old project. I'm wondering if anyone has advice on how to tackle the new software help so it doesn't become like the old. My boss is pressuring me to pull each client into a separate project but I see the benefit of conditions and don't see separate projects working well for single-sourcing. I know it's hard without seeing the project, but here's what I have:
Single set of topics
Single TOC
Target for each client, conditions are set to Include for that client and Exclude for all other clients
Condition tags are client names only
If anyone has any suggestions please let me know. I'd also like to see if anyone has advice on how to best set up conditional tag sets based on this scenario.
Thanks!
Taylor
Inherited Project, Need Advice
-
- Sr. Propeller Head
- Posts: 210
- Joined: Mon Sep 19, 2011 2:06 am
- Location: Netherlands - Zoetermeer
- Contact:
Re: Inherited Project, Need Advice
Hi,
What I would do in this case:
Create 1 new project.
For each client, create a target.
Create a condition set that contains only ExcludeFrom<Client> conditions.
Depending on how much overlap is inside the text (topics) going into the output for the clients, either create 1 TOC (most texts are shared) or create a TOC that contains the most of the shared topics and additional TOCs for the remaining topics (or even a separate TOC in case there is (almost) no shared info between clients).
In the TOC, create the chapters (books) as in the current version(s), and next add the existing texts (topics) to them. If time is lacking, first add the texts only to be able to deliver and when time is available, start creating snippets for the same texts.
In the added texts ONLY apply ExcludeFrom<Client> conditions to those text(-parts) that must be excluded for that Client(output). ( avoid using Includes - makes the sources much and much more maintainable - the rule is that al text is always included by default, so when really needed to use an include condition, there is 99.99% chance a rewrite can solve this issue).
And use a versioning program, like Perforce for example, to branch each finished version from your "development-tree".
Hope this info is of some help to you,
Greetings,
Rene Severens
What I would do in this case:
Create 1 new project.
For each client, create a target.
Create a condition set that contains only ExcludeFrom<Client> conditions.
Depending on how much overlap is inside the text (topics) going into the output for the clients, either create 1 TOC (most texts are shared) or create a TOC that contains the most of the shared topics and additional TOCs for the remaining topics (or even a separate TOC in case there is (almost) no shared info between clients).
In the TOC, create the chapters (books) as in the current version(s), and next add the existing texts (topics) to them. If time is lacking, first add the texts only to be able to deliver and when time is available, start creating snippets for the same texts.
In the added texts ONLY apply ExcludeFrom<Client> conditions to those text(-parts) that must be excluded for that Client(output). ( avoid using Includes - makes the sources much and much more maintainable - the rule is that al text is always included by default, so when really needed to use an include condition, there is 99.99% chance a rewrite can solve this issue).
And use a versioning program, like Perforce for example, to branch each finished version from your "development-tree".
Hope this info is of some help to you,
Greetings,
Rene Severens
"The numbers are strange today; they somehow do not seem to add up."
Re: Inherited Project, Need Advice
Thanks for the advice Rene. I have seen several people suggest using conditions for exclude only. I see how this would make maintaining tags easier, however for this software I'm not sure if it makes sense. Most additional features (at least for the start of this new software) will only go to one or two clients and will not be part of the baseline software. For example, this week I need to add information for a report that is only going to be available for a single client, and will never be included in a broad software release. Does it make sense to have a topic with 34 excludes versus 1 include? Maybe I just need to change my frame of mind about conditions.
If that information were a single topic, would it make more sense to just create a separate TOC for that client? I could see that becoming hard to manage as time went on.
I have never managed a project like this so I just want to understand others' experiences.
If that information were a single topic, would it make more sense to just create a separate TOC for that client? I could see that becoming hard to manage as time went on.
I have never managed a project like this so I just want to understand others' experiences.
Re: Inherited Project, Need Advice
This kind of project is going to be a mess no matter what you do. Try to tailor the conditions to match the underlying logic. Try to make it easy on yourself when you get a new client, or when a client adds a feature, because in your kind of situation that is certainly going to happen. If your business is successful it will happen a lot.
For stuff that is customized for a single customer, have a tag like client_specific that gets applied to all such text and is excluded from all clients, along with individual client tags to include that material.
This will mean you have to apply two conditions together (client_specific and client_A, for instance).
You can also have not_client_A conditions for those item excluded from one or two customers.
When you add a new client, in their target exclude client_specific and include client_name and exclude not_client_name and this stuff will all be correct. No need to go into the code and find specific help that needs to get a new client_exclude tag on it. (You need not actually create all those client_name and not_client_name conditions if some
Where text applies to a specific feature, have a condition named for that feature and exclude it from clients that don't have it. If a client adds a feature, you can stop excluding that feature from that client.
When you get a new client, exclude from their target whichever features they don't have. Again, no need to go find specific help to change conditions on.
This method will lead to a lot of conditions. But when the customer/feature matrix changes, you only need to reconfigure targets, not change conditions within topics/TOCs. This changing topics is most likely the reason the conditions in the old help weren't right.
For stuff that is customized for a single customer, have a tag like client_specific that gets applied to all such text and is excluded from all clients, along with individual client tags to include that material.
This will mean you have to apply two conditions together (client_specific and client_A, for instance).
You can also have not_client_A conditions for those item excluded from one or two customers.
When you add a new client, in their target exclude client_specific and include client_name and exclude not_client_name and this stuff will all be correct. No need to go into the code and find specific help that needs to get a new client_exclude tag on it. (You need not actually create all those client_name and not_client_name conditions if some
Where text applies to a specific feature, have a condition named for that feature and exclude it from clients that don't have it. If a client adds a feature, you can stop excluding that feature from that client.
When you get a new client, exclude from their target whichever features they don't have. Again, no need to go find specific help to change conditions on.
This method will lead to a lot of conditions. But when the customer/feature matrix changes, you only need to reconfigure targets, not change conditions within topics/TOCs. This changing topics is most likely the reason the conditions in the old help weren't right.
-
- Propeller Head
- Posts: 88
- Joined: Wed May 25, 2016 3:35 pm
Re: Inherited Project, Need Advice
I agree with Rene that leveraging separate TOCs for each client/type of compilation would be most helpful for you (remember to set the TOC to master so it publishes the one you want!).tkhint wrote:Thanks for the advice Rene. I have seen several people suggest using conditions for exclude only. I see how this would make maintaining tags easier, however for this software I'm not sure if it makes sense. Most additional features (at least for the start of this new software) will only go to one or two clients and will not be part of the baseline software. For example, this week I need to add information for a report that is only going to be available for a single client, and will never be included in a broad software release. Does it make sense to have a topic with 34 excludes versus 1 include? Maybe I just need to change my frame of mind about conditions.
If that information were a single topic, would it make more sense to just create a separate TOC for that client? I could see that becoming hard to manage as time went on.
I have never managed a project like this so I just want to understand others' experiences.
You can right click a topic and then click "Locate in TOC," which is quite helpful.
I've also made folders of the main topics for each of the sections of a manual I'm working on and then created separate TOCs for what topics need to be in different projects. Good luck!
~Sarah
Technical Writer using and experimenting with Flare version 12.0.5991.
Re: Inherited Project, Need Advice
Are you tasked to maintain custom documentation for each of these clients? That's madness. You need to point out how much effort this is and that it won't scale if it adds more clients. You need to make an argument to be able to produce a single output and put in caveats on the topics that not all features apply to all clients.tkhint wrote:Hello all,
I hope this is the correct place to post this. Quick backstory, I recently took a job and inherited multiple projects. The company provides a software platform to approximately 35 clients, with the baseline software being specifically tailored to each client. This includes both additional features and subtraction of baseline features. From what I have seen so far, differences typically apply to either a third of the clients, two thirds, all but one or two, or only to one or two. One project is for the older version of the software, and was worked on by three separate writers, so it's a bit of a mess. The current outputs are wrong for many clients, and after a week of digging in I think this is mainly because of the way the conditional tags have been applied. They are applied inline, on block level, html level, and topic level pretty inconsistently. A lot of topics are conditioned for all except one client (there is one condition tag set that is a list of all of the clients, that is all).
I've been told the old software will not really be updated anymore, as they just launched a new software that will start going to new clients. My predecessor set up the new help project, which is much cleaner, but she set it up the same way as the old project. I'm wondering if anyone has advice on how to tackle the new software help so it doesn't become like the old. My boss is pressuring me to pull each client into a separate project but I see the benefit of conditions and don't see separate projects working well for single-sourcing. I know it's hard without seeing the project, but here's what I have:
Single set of topics
Single TOC
Target for each client, conditions are set to Include for that client and Exclude for all other clients
Condition tags are client names only
If anyone has any suggestions please let me know. I'd also like to see if anyone has advice on how to best set up conditional tag sets based on this scenario.
Thanks!
Taylor
I'm guessing the reason you've inherited such a mess is because the previous person didn't know what they were doing and didn't know how to push back against this kind of insanity. Perhaps also the reason they're not there any more.