Best practice single source
Best practice single source
Hi,
I want to give a try to the following project. There's a complete document that contains numerous sections. There is a subdocument that contains a few of those sections. I want to author my content only once. Each section contains several procedures with supporting images.
What are the best practices for me to set up my Flare 12 project so that I can create one document with all the sections and a second document with only a few of the sections.
Assume PDF output for both.
Thoughts?
Cheers,
Sean
I want to give a try to the following project. There's a complete document that contains numerous sections. There is a subdocument that contains a few of those sections. I want to author my content only once. Each section contains several procedures with supporting images.
What are the best practices for me to set up my Flare 12 project so that I can create one document with all the sections and a second document with only a few of the sections.
Assume PDF output for both.
Thoughts?
Cheers,
Sean
Re: Best practice single source
For example, do I do this by manipulating tables of content?
Such as, I create one toc for the larger document and one toc for the smaller document? Output the larger toc to PDF for that entire content, and output the smaller toc to PDF for the subdocument?
That seems to be what I should try. I don't fancy using conditions for this.
Sean
Such as, I create one toc for the larger document and one toc for the smaller document? Output the larger toc to PDF for that entire content, and output the smaller toc to PDF for the subdocument?
That seems to be what I should try. I don't fancy using conditions for this.
Sean
-
- Senior Propellus Maximus
- Posts: 3669
- Joined: Thu Feb 02, 2006 9:57 am
- Location: Pittsford, NY
Re: Best practice single source
Hi Sean.
There is no one-size-fits-all best practice. But your proposed solution should work just fine. Other authors might have a single TOC and then condition it somehow to keep things out of the short document. But there is no rule that says that you can’t have two TOCs, one for the full doc and the other for the short doc, as you describe. If that seems easier and more intuitive, go for it. It also might be more fail-safe. You won’t run the risk of forgetting to condition a TOC entry and then have it show up in the short doc. (FWIW, I use multiple TOCs for different PDF outputs, instead of one giant, condition-laden TOC.)
There is no one-size-fits-all best practice. But your proposed solution should work just fine. Other authors might have a single TOC and then condition it somehow to keep things out of the short document. But there is no rule that says that you can’t have two TOCs, one for the full doc and the other for the short doc, as you describe. If that seems easier and more intuitive, go for it. It also might be more fail-safe. You won’t run the risk of forgetting to condition a TOC entry and then have it show up in the short doc. (FWIW, I use multiple TOCs for different PDF outputs, instead of one giant, condition-laden TOC.)
Nita
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
Re: Best practice single source
Thanks.
So, what you are saying, is that some people might use one toc and use a condition for each of the separate sub documents it spawns? I might try that, but my approach seems more ... clear.
Cheers,
Sean
So, what you are saying, is that some people might use one toc and use a condition for each of the separate sub documents it spawns? I might try that, but my approach seems more ... clear.
Cheers,
Sean
-
- Senior Propellus Maximus
- Posts: 3669
- Joined: Thu Feb 02, 2006 9:57 am
- Location: Pittsford, NY
Re: Best practice single source
Clarity matters. Simplicity is important. My philosophy as a Flare designer is to always seek the simplest solution, the clearest solution, as that will be easiest for anyone who follows me to maintain the projects I design.
Nita
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
-
- Propellus Maximus
- Posts: 613
- Joined: Wed Feb 01, 2006 6:21 am
- Location: Off in the dark....
Re: Best practice single source
I've managed a couple of large projects using conditions. As Nita mentioned, it can get cumbersome. But project also had conditional text within topics for the different outputs/product versions, so the multi-TOC didn't really work for me.
If you can tailor your TOCs and then use the do not link un-referenced files setting to exclude the rest, you're golden.
If you can tailor your TOCs and then use the do not link un-referenced files setting to exclude the rest, you're golden.
Trent.
Certifiable.
umm...
I meant MAD Certified.
Official Propeller Beanie Owner
Are you on Flare's Slack channels? PM me for an invitation!
Certifiable.
umm...
I meant MAD Certified.
Official Propeller Beanie Owner
Are you on Flare's Slack channels? PM me for an invitation!
-
- Senior Propellus Maximus
- Posts: 3669
- Joined: Thu Feb 02, 2006 9:57 am
- Location: Pittsford, NY
Re: Best practice single source
Our friend is building PDFs, so the “do not link in-referenced files setting” (aka “Exclude content not directly or indirectly linked to the target”) isn’t applicable.trent the thief wrote:...and then use the do not link un-referenced files setting to exclude the rest, you're golden.
Nita
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
Re: Best practice single source
I'm doing something similar... and I just want to run it past people with more experience before I get too far into it all.
I have:
When I'm not around (I'm freelance, and this is only one of many clients) the developers want to be able to make minor corrections themselves.
So, my plan is:
So far about 95% of the topics are common to all outputs, but that will reduce (it just happens to be that the first three products were based on each other - there are currently 8 active products that can be categorised into 3 product types, and I've just done one type). Of those 95%, about 10% contain conditioned paragraphs... slight variations in instructions. All other differences are sorted using variables, which are defined in the targets, as are the conditions.
This means:
1 - I don't have to tag the ToC itself. It makes it easier for the developers to navigate...if it's in the ToC, it's in the PDF, and in that order.
2 - I don't have to worry about correctly tagging topics to exclude (and more importantly, neither does anyone else... if they aren't in the ToC, they don't get built).
My question... Am I missing something fundamental here? Am I setting myself up to fail? (I may end up with 20-odd targets, but I doubt it will ever get to more than that. I've been involved with this company for nearly 20 years, and they've always had around 10 active products maximum.)
I have:
- One large Flare project (only just migrating, so not that large yet)
- So far, 3 PDF outputs (different products) and 3 HTML outputs (for each of the products) - HTML is just the individual topics... I'm building a web output but the developers only use the individual pages linked directly to individual pages in the product and the rest is ignored. (As an aside, I was hoping to share topics across the help and the PDF, but so far haven't worked out how. It's not a technical issue - it's more that I have fixed size to play with on the web pages before it becomes unwieldy for the user because of how they are linked and the fixed window.)
When I'm not around (I'm freelance, and this is only one of many clients) the developers want to be able to make minor corrections themselves.
So, my plan is:
- Have one target per output
- Have one ToC per output
So far about 95% of the topics are common to all outputs, but that will reduce (it just happens to be that the first three products were based on each other - there are currently 8 active products that can be categorised into 3 product types, and I've just done one type). Of those 95%, about 10% contain conditioned paragraphs... slight variations in instructions. All other differences are sorted using variables, which are defined in the targets, as are the conditions.
This means:
1 - I don't have to tag the ToC itself. It makes it easier for the developers to navigate...if it's in the ToC, it's in the PDF, and in that order.
2 - I don't have to worry about correctly tagging topics to exclude (and more importantly, neither does anyone else... if they aren't in the ToC, they don't get built).
My question... Am I missing something fundamental here? Am I setting myself up to fail? (I may end up with 20-odd targets, but I doubt it will ever get to more than that. I've been involved with this company for nearly 20 years, and they've always had around 10 active products maximum.)
Alison
Lone technical author - Flare user since March 2017
Currently using Flare 2020
Lone technical author - Flare user since March 2017
Currently using Flare 2020
Re: Best practice single source
The one thing you'll get yourself into is if you add core functionality that requires new topics in shared material that spans across all products, you'll have to edit all the TOCs to include the new topic. Given your other concerns, and especially if this is considered unlikely, then you may accept the risk/work required is less pain than the alternatives.
Re: Best practice single source
Thank you. I'm fairly relaxed about that... Adding a topic or two to two or three To six seems a small price to pay. Alison
Alison
Lone technical author - Flare user since March 2017
Currently using Flare 2020
Lone technical author - Flare user since March 2017
Currently using Flare 2020
Re: Best practice single source
You can also include tocs within other tocs - I find this useful for modules that are shared across different products. This is good for when I'm updating documentation for that module and I need to add the changes to all the supertocs.
Re: Best practice single source
I didn't know you could do that... absolutely brilliant!
Thanks a bunch... Alison
Thanks a bunch... Alison
Alison
Lone technical author - Flare user since March 2017
Currently using Flare 2020
Lone technical author - Flare user since March 2017
Currently using Flare 2020
Re: Best practice single source
If you are building html output, you can configure how the subtoc is merged when the output is built. The options are on the Advanced tab of the subtoc properties. I usually choose to replace the node with the merged toc.