So,
I've been furiously reading stuff on Flare, single-sourcing, and I am a newbie that (thinks) he has a game plan. I thought I'd check in here in broad strokes and see if it made any sense or if there were any suggestions.
The main issue is that one of the software programs that I document is massively customized. It has three major "sub-types" with mostly the same content, but then 40+ client customized versions based off of those three types. Most of these customizations are small (software tools included or omitted, processes that are slightly different).
So, here are my questions:
1) Would creating a new target for most of these customizations, instead of a new linked project, make sense? I feel like creating a target for each client version, overwriting the ClientName variable, and modifying the ToC to reflect the changes for the client would be the best way to go. There would be some conditional tagging of content in topics and some conditional tagging of entirely different topic versions when the customizations are too severe. There would be a Clients condition tag set, and i was planning on giving every client tag the same color (I'm colorblind, so I can't use the full spectrum of tags and have them mean anything visually).
2) Should I condition tag "core/shared" materials that will be shared between virtually every version of the document? I've seen some people recommend that, and was curious as to what advantage it offers exactly.
3) How do people manage web-help with tons of client customizations? Is there a web-help for each client, or do you just provide "core" web-help, or do you provide one web-help where everyone has access to everyone else's customizations as well?
I realize this is a hard thing to do with so little information, but hopefully these questions are general enough that people can share some experiences/advice. Thanks!!
The Plan(tm)
The Plan(tm)
-Dan, Propellerhead-in-training
-
doc_guy
- Propellus Maximus
- Posts: 1979
- Joined: Tue Nov 28, 2006 11:18 am
- Location: Crossroads of the West
- Contact:
Re: The Plan(tm)
Hey dorcutt.
So, from what I can tell, The Planâ„¢ sounds good.
It is a real pain in the neck tracking individual customer customizations. The right path depends on how much reuse there is between customer customizations, and how much maintenance you have to do for each customer. For one client, whose primary deliverables are all PDF documents, I have created the base product guide in Flare, and then I generate a Word document for specific customers. I can then update whatever I need for specific customers, including their custom modifications. But that only works because we don't have ongoing maintenance requirements for those customers. We sell them the software with customizations and at the end of our contract with them, we don't support their systems anymore.
I started trying to track individual client customizations in Flare using conditions, and while it is possible, it gets complicated very quickly. In the case I mentioned above, the company has about 10 products that interact with each other, but can be purchased separately or in any combination. We work with each customer and customize the software for their needs. In that case, generating docs from the base standard and then workign in those docs for specific customers is the best solution.
If I had to provide webhelp output for each client, I'd probably have a master project that is the baseline for the product, and then I'd create child projects using the Flare import project functionality, and just change those topics that are different for that client.
Hope that helps.
-Paul
So, from what I can tell, The Planâ„¢ sounds good.
It is a real pain in the neck tracking individual customer customizations. The right path depends on how much reuse there is between customer customizations, and how much maintenance you have to do for each customer. For one client, whose primary deliverables are all PDF documents, I have created the base product guide in Flare, and then I generate a Word document for specific customers. I can then update whatever I need for specific customers, including their custom modifications. But that only works because we don't have ongoing maintenance requirements for those customers. We sell them the software with customizations and at the end of our contract with them, we don't support their systems anymore.
I started trying to track individual client customizations in Flare using conditions, and while it is possible, it gets complicated very quickly. In the case I mentioned above, the company has about 10 products that interact with each other, but can be purchased separately or in any combination. We work with each customer and customize the software for their needs. In that case, generating docs from the base standard and then workign in those docs for specific customers is the best solution.
If I had to provide webhelp output for each client, I'd probably have a master project that is the baseline for the product, and then I'd create child projects using the Flare import project functionality, and just change those topics that are different for that client.
Hope that helps.
-Paul
Re: The Plan(tm)
Thanks doc-guy, that does help quite a bit actually! I had never really considered the "export as Word and maintain there." That might work for some of our clients who do not have maintenance contracts, which is a good number of them, and may help to thin down the herd significantly. If I can winnow out some clients, I think the custom tags will work much better.
Have you or anyone else ever dealt with creating a web-help for a product with multiple client customizations? That is where I have literally no idea where to start. I suspect that the answer is to just create a generic web-help and ignore the client specifications thing, perhaps unless the client is willing to pay for a "customized web help" upgrade.
Have you or anyone else ever dealt with creating a web-help for a product with multiple client customizations? That is where I have literally no idea where to start. I suspect that the answer is to just create a generic web-help and ignore the client specifications thing, perhaps unless the client is willing to pay for a "customized web help" upgrade.
-Dan, Propellerhead-in-training
Re: The Plan(tm)
Having all the content in one project and using conditions for each client would work - there's no problems technically, it's more about finding a good system to organise it.
As doc-guy suggested, you could also use project imports, which would remove/reduce the need for some of the conditions. In this scenario, you could create individual client projects that import 'core' content from a master project; then tailor the project for the client. However, this only really works if you (a) don't need to modify the imported content, or (b) will modify the imported content, but will never need to re-import that content from the original (i.e. if the original content is updated).
One thing that hasn't been mentioned in this thread is variables. You can use a variable for a word/phrase (string) that is different between clients (e.g. company or product name), and change the variable text in each individual target.
As doc-guy suggested, you could also use project imports, which would remove/reduce the need for some of the conditions. In this scenario, you could create individual client projects that import 'core' content from a master project; then tailor the project for the client. However, this only really works if you (a) don't need to modify the imported content, or (b) will modify the imported content, but will never need to re-import that content from the original (i.e. if the original content is updated).
One thing that hasn't been mentioned in this thread is variables. You can use a variable for a word/phrase (string) that is different between clients (e.g. company or product name), and change the variable text in each individual target.
-
doc_guy
- Propellus Maximus
- Posts: 1979
- Joined: Tue Nov 28, 2006 11:18 am
- Location: Crossroads of the West
- Contact:
Re: The Plan(tm)
Yeah. The importing into child projects idea only really works because we provide a one-time help system to a client with their modifications. We don't release updates to them, so we don't need to maintain their documentation. I would just import the parent project into the child project, break the links with any files I needed to update (because I'll never be re-importing content into the project again), generate the output, and then archive the project. There would be no active development in that project after that point.
Variables are a great way to be able to customize content for a specific client. I worked for a company that created web portal pages for colleges and universities. We used variables or the portal name, which was different at each school. We generated a web output for each client with their custom portal name for the variable definition (which is controlled/changed in the target file).
Conditions get unwieldy when you have 50+ clients that have their own customizations. At some point you get to a point of diminishing returns when you have a five paragraph topic that has customizations for 50 different clients. With that level of specificity, there's only so much you can do. You might create a basic system that covers default functionality, and then create a specific document (maybe even in Word) that has documentation on the updates/customizations made for that client. That way, you minimize the customizations done in the Flare project, but you still give the client details about what you changed for them.
Variables are a great way to be able to customize content for a specific client. I worked for a company that created web portal pages for colleges and universities. We used variables or the portal name, which was different at each school. We generated a web output for each client with their custom portal name for the variable definition (which is controlled/changed in the target file).
Conditions get unwieldy when you have 50+ clients that have their own customizations. At some point you get to a point of diminishing returns when you have a five paragraph topic that has customizations for 50 different clients. With that level of specificity, there's only so much you can do. You might create a basic system that covers default functionality, and then create a specific document (maybe even in Word) that has documentation on the updates/customizations made for that client. That way, you minimize the customizations done in the Flare project, but you still give the client details about what you changed for them.