[Framers] reused content for different products - best practices ?

[Shmuel Wolfson]

I don't think you need structured FM for this. You can share the 
appendix chapter in all the relevant books and mark the differences 
between the products with conditional text. As far as variables, you can 
either have multiple variables for the different products (product1, 
product2, product3) and mark them with conditional text, or you can use 
the same variable name for all products and import a "template" for each 
product that contains the variable definitions for each product. I 
usually prefer the 1st option.

I would only use text insets for parts of a chapter, not an entire 
chapter. You can use conditional text in text insets as well.

If you do localization (translation), than it makes sense to go with 
structured FM.

--
Shmuel Wolfson
Technical Writer
058-763-7133

On 17-May-16 10:01 PM, Monique Semp wrote:
> Hello, Framers,
>
> I’ve got an appendix that now should be shared among three different products’ docs, and among multiple docs for the same product, and I’m looking for best practices re: conditions vs. variables vs. text insets.
>
> (Sorry this is a long post. Just click delete if you’re not into the minutia of this stuff. Otherwise, you’ll see my specific questions marked by “**Q”.)
>
> The relevant diffs in this appendix are:
>
>    1. Product name—Scattered throughout the content, where it talks about things such as “<product-name> scripts” and “<product-name> script entry”.
>
>    2. Doc part number—Appears in headers. I already have a variable that’s different in every doc, so this is taken care of.
>
>    3. Info that’s only for the original product in which this appendix appeared—Phrases and standalone sentences in almost every reference entry for a script element. But the point isn’t that it’s only for the first product, but for when we’re describing lower-level code details, which we do for some products but not all. I’ve used a condition, __INCLUDE_<struct-name>_info, which seems straight-forward and easily extended for future products without getting into exactly which products need this content.
>
>    4. Sample script file—Different for each product.
> So two are easily managed, and I’m looking for advice on the other two:
>
> * Item 1 (product name): Conditionals would be a real pain, and I’d have to add a new condition every time I needed this appendix for another product/doc. A variable could be used, which I guess would be .fm file-specific.
>
> But the odd thing here is that I already have a variable for one of the products (for which there are two docs), but this variable isn’t named generically; it’s name is “_prod_name_<short-version>” because there’s a space in the actual product name, and I wanted to ensure that the product name didn’t break across lines. So if I wanted a variable for this new use—to control which product name is included in the content—I’d either have to commit variable abuse (assigning a value that contradicts the actual variable name) or add a new variable.
>
> **Q: Adding a new variable seems best, with a generic name. But should that variable be just for this file, or should I make it more general and use it across all files in a book?
>
> * Item 4 (different script file): This wouldn’t be hard to manage with conditions—just add a condition for each product or product-component—but I’m concerned with proliferating conditions. I’ve tried hard to keep the conditions to a minimum to avoid getting into complex condition evaluation and usage. And I just don’t know what the future will bring.
>
> So an alternative thought is to have a separate .fm file for each book (for each product or product-component, that is), which would include a text inset that contains only the common content (with variables and conditions as described above), and then directly include the specific script sample.
>
> **Q: Are there issues I should look out for in terms of using variables and conditions (the __INCLUDE_<struct-name>_info) in a text inset? Perhaps it’s best to create a set of conditions now for each product/product-component on the assumption that they’ll likely turn out useful in the future? Are there easier/better-suited mechanisms that I’m just overlooking?
>
> Thanks for the advice,
> -Monique
>
>
>
> _______________________________________________
>
> This message is from the Framers mailing list
>
> Send messages to framers at lists.frameusers.com
> Visit the list's homepage at  http://www.frameusers.com
> Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/
> Subscribe and unsubscribe at http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
> Send administrative questions to listadmin at frameusers.com