Best practice single source

This forum is for Single-Sourcing your Flare content to multiple outputs.
Post Reply
Sean
Propeller Head
Posts: 57
Joined: Mon Apr 14, 2014 7:45 am

Best practice single source

Post by Sean »

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
Sean
Propeller Head
Posts: 57
Joined: Mon Apr 14, 2014 7:45 am

Re: Best practice single source

Post by Sean »

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
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: Best practice single source

Post by Nita Beck »

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.)
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
Sean
Propeller Head
Posts: 57
Joined: Mon Apr 14, 2014 7:45 am

Re: Best practice single source

Post by Sean »

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
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: Best practice single source

Post by Nita Beck »

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
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
trent the thief
Propellus Maximus
Posts: 608
Joined: Wed Feb 01, 2006 6:21 am
Location: Off in the dark....

Re: Best practice single source

Post by trent the thief »

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.
Trent.

Certifiable.

Image

umm...
I meant MAD Certified.

Official Propeller Beanie Owner :-)

:flare: Are you on Flare's Slack channels? PM me for an invitation! :flare:
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: Best practice single source

Post by Nita Beck »

trent the thief wrote:...and then use the do not link un-referenced files setting to exclude the rest, you're golden.
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.
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
ajpeck123
Propeller Head
Posts: 37
Joined: Tue Mar 07, 2017 6:01 am

Re: Best practice single source

Post by ajpeck123 »

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:
  • 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.)
The release engineer likes to take the source and build the PDFs himself (to check it's all working, I think :) )
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
Because the developers won't be familiar with the Flare project setup, I'm thinking of telling them to open the correct ToC and then open the file they want to edit from that... that way, they won't inadvertently open a topic that contains similar information but is for a different product. It also means that as their starting point will be the previously created PDF, they will find what they want relatively easily. Building the targets is then very straightforward.

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
devjoe
Sr. Propeller Head
Posts: 337
Joined: Thu Jan 23, 2014 1:43 pm

Re: Best practice single source

Post by devjoe »

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.
ajpeck123
Propeller Head
Posts: 37
Joined: Tue Mar 07, 2017 6:01 am

Re: Best practice single source

Post by ajpeck123 »

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
jjw
Sr. Propeller Head
Posts: 133
Joined: Thu May 08, 2014 4:18 pm
Location: Melbourne

Re: Best practice single source

Post by jjw »

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.
ajpeck123
Propeller Head
Posts: 37
Joined: Tue Mar 07, 2017 6:01 am

Re: Best practice single source

Post by ajpeck123 »

I didn't know you could do that... absolutely brilliant!
Thanks a bunch... Alison
Alison
Lone technical author - Flare user since March 2017
Currently using Flare 2020
jjw
Sr. Propeller Head
Posts: 133
Joined: Thu May 08, 2014 4:18 pm
Location: Melbourne

Re: Best practice single source

Post by jjw »

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.
Post Reply