RE: Structured docs or conditional text
Hi Carl, Depending on the amount that your installation instructions differs between platforms, you may want to consider using separate docs with text insets (and variables, if appropriate) in addition to conditionalized text. I have found that for sections of the installation steps that vary only in product name, you can cut the text, put it in a separate document, refer to the product as a variable (example: "navigate to the [product] installation folder..."), and then import that file as a text inset. Repeat for each large chunk of nearly identical sections. Whether this is a good solution depends on your preference and the way your material varies. If you go with conditional text, I recommend conditionalizing by whole sentences or whole phrases, rather than letters or words. It will reduce the brain power you have to use to make sure all the spacing/grammar is correct. :) Cheers, Callie Bertsche Tecplot, Inc. From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com <mailto:framers-boun...@lists.frameusers.com> ] On Behalf Of Carl Yorke Sent: Tuesday, March 24, 2009 5:11 PM To: framers@lists.frameusers.com Subject: Structured docs or conditional text Hi All, I came to tech writing late in life (ten years ago), so there's a lot about it, and technology, that doesn't come naturally. I want to single source my install instructions. All outputs right now are PDF, but I need to document how to install our product for production, for QA, and for demos. In addition, the install instructions vary depending on the hardware. Conditional text seems awfully complex for this situation, and I don't even know if using structured FrameMaker is a possible solution. Any thoughts? Thanks, Carl Yorke ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Structured docs or conditional text
Hi Carl, Depending on the amount that your installation instructions differs between platforms, you may want to consider using separate docs with text insets (and variables, if appropriate) in addition to conditionalized text. I have found that for sections of the installation steps that vary only in product name, you can cut the text, put it in a separate document, refer to the product as a variable (example: "navigate to the [product] installation folder..."), and then import that file as a text inset. Repeat for each large chunk of nearly identical sections. Whether this is a good solution depends on your preference and the way your material varies. If you go with conditional text, I recommend conditionalizing by whole sentences or whole phrases, rather than letters or words. It will reduce the brain power you have to use to make sure all the spacing/grammar is correct. :) Cheers, Callie Bertsche Tecplot, Inc. From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com <mailto:framers-bounces at lists.frameusers.com> ] On Behalf Of Carl Yorke Sent: Tuesday, March 24, 2009 5:11 PM To: framers at lists.frameusers.com Subject: Structured docs or conditional text Hi All, I came to tech writing late in life (ten years ago), so there's a lot about it, and technology, that doesn't come naturally. I want to single source my install instructions. All outputs right now are PDF, but I need to document how to install our product for production, for QA, and for demos. In addition, the install instructions vary depending on the hardware. Conditional text seems awfully complex for this situation, and I don't even know if using structured FrameMaker is a possible solution. Any thoughts? Thanks, Carl Yorke
Structured docs or conditional text
In essence, both can do what you want. Structured language is easier to manage, but more difficult and expensive to initiate. Conditional text will work, you have to know what conditions are exclusive, which are inclusive with which scenarios, and structure the conditions that way. It can be tricky. Scott Carl Yorke wrote: > Hi All, > > I came to tech writing late in life (ten years ago), so there's a lot > about it, and technology, that doesn't come naturally. > > > > I want to single source my install instructions. All outputs right now > are PDF, but I need to document how to install our product for > production, for QA, and for demos. In addition, the install instructions > vary depending on the hardware. > > > > Conditional text seems awfully complex for this situation, and I don't > even know if using structured FrameMaker is a possible solution. > > > > Any thoughts? > > > > Thanks, > > Carl Yorke > > TAG Systems > > Mountain View, CA > > ___ > > > You are currently subscribed to Framers as quills at airmail.net. > > Send list messages to framers at lists.frameusers.com. > > To unsubscribe send a blank email to > framers-unsubscribe at lists.frameusers.com > or visit > http://lists.frameusers.com/mailman/options/framers/quills%40airmail.net > > Send administrative questions to listadmin at frameusers.com. Visit > http://www.frameusers.com/ for more resources and info. > > >
Structured docs or conditional text
Carl, The answer is both flavors of Frame will handle Conditional Text with ease, and from what you say below, conditional text is the way to go, whether it be structured or unstructured. A few things to consider: 1) Decide on an input scheme, always put the differences in the document in the same order, i.e., unconditional, condition1, condition2, condition3, etc. If an instance occurs that doesn't use a particular condition, still maintain the overall scheme. 2) When you have two conditions in, turn one off and make sure the sentence reads correct. Change as required. 3) Watch out for table cells. In unstructured Frame, you can conditionalize rows, not columns. In structured Frame, create multiple copies of the table, make the changes, then conditionalize the entire table (at least that has been my experience). 4) You can conditionalize individual content within a cell. 5) In unstructured Frame, watch carefully when selecting entire lines (paragraphs, bullets in lists, etc. Make sure you capture the entire line, including the end-of-line (turn on View Text Symbols). 6) In structured Frame you can select the element in the Structured View, which simplifies matters. 7) Probably a no-brainer, but set your conditions before creating your PDF. The PDF will then contain only the conditions that are turned on in the Frame file. I am sure you will hear from others, either correcting some of the above points or pointing out some options I missed. HTH Dave Spreadbury -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Carl Yorke Sent: Tuesday, March 24, 2009 5:11 PM To: framers at lists.frameusers.com Subject: Structured docs or conditional text Hi All, I came to tech writing late in life (ten years ago), so there's a lot about it, and technology, that doesn't come naturally. I want to single source my install instructions. All outputs right now are PDF, but I need to document how to install our product for production, for QA, and for demos. In addition, the install instructions vary depending on the hardware. Conditional text seems awfully complex for this situation, and I don't even know if using structured FrameMaker is a possible solution. Any thoughts? Thanks, Carl Yorke
Re: Structured docs or conditional text
In essence, both can do what you want. Structured language is easier to manage, but more difficult and expensive to initiate. Conditional text will work, you have to know what conditions are exclusive, which are inclusive with which scenarios, and structure the conditions that way. It can be tricky. Scott Carl Yorke wrote: > Hi All, > > I came to tech writing late in life (ten years ago), so there's a lot > about it, and technology, that doesn't come naturally. > > > > I want to single source my install instructions. All outputs right now > are PDF, but I need to document how to install our product for > production, for QA, and for demos. In addition, the install instructions > vary depending on the hardware. > > > > Conditional text seems awfully complex for this situation, and I don't > even know if using structured FrameMaker is a possible solution. > > > > Any thoughts? > > > > Thanks, > > Carl Yorke > > TAG Systems > > Mountain View, CA > > ___ > > > You are currently subscribed to Framers as qui...@airmail.net. > > Send list messages to fram...@lists.frameusers.com. > > To unsubscribe send a blank email to > framers-unsubscr...@lists.frameusers.com > or visit > http://lists.frameusers.com/mailman/options/framers/quills%40airmail.net > > Send administrative questions to listad...@frameusers.com. Visit > http://www.frameusers.com/ for more resources and info. > > > ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Structured docs or conditional text
Carl, The answer is both flavors of Frame will handle Conditional Text with ease, and from what you say below, conditional text is the way to go, whether it be structured or unstructured. A few things to consider: 1) Decide on an input scheme, always put the differences in the document in the same order, i.e., unconditional, condition1, condition2, condition3, etc. If an instance occurs that doesn't use a particular condition, still maintain the overall scheme. 2) When you have two conditions in, turn one off and make sure the sentence reads correct. Change as required. 3) Watch out for table cells. In unstructured Frame, you can conditionalize rows, not columns. In structured Frame, create multiple copies of the table, make the changes, then conditionalize the entire table (at least that has been my experience). 4) You can conditionalize individual content within a cell. 5) In unstructured Frame, watch carefully when selecting entire lines (paragraphs, bullets in lists, etc. Make sure you capture the entire line, including the end-of-line (turn on View Text Symbols). 6) In structured Frame you can select the element in the Structured View, which simplifies matters. 7) Probably a no-brainer, but set your conditions before creating your PDF. The PDF will then contain only the conditions that are turned on in the Frame file. I am sure you will hear from others, either correcting some of the above points or pointing out some options I missed. HTH Dave Spreadbury -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Carl Yorke Sent: Tuesday, March 24, 2009 5:11 PM To: framers@lists.frameusers.com Subject: Structured docs or conditional text Hi All, I came to tech writing late in life (ten years ago), so there's a lot about it, and technology, that doesn't come naturally. I want to single source my install instructions. All outputs right now are PDF, but I need to document how to install our product for production, for QA, and for demos. In addition, the install instructions vary depending on the hardware. Conditional text seems awfully complex for this situation, and I don't even know if using structured FrameMaker is a possible solution. Any thoughts? Thanks, Carl Yorke ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Structured docs or conditional text
Hi All, I came to tech writing late in life (ten years ago), so there's a lot about it, and technology, that doesn't come naturally. I want to single source my install instructions. All outputs right now are PDF, but I need to document how to install our product for production, for QA, and for demos. In addition, the install instructions vary depending on the hardware. Conditional text seems awfully complex for this situation, and I don't even know if using structured FrameMaker is a possible solution. Any thoughts? Thanks, Carl Yorke TAG Systems Mountain View, CA ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Structured docs or conditional text
Hi All, I came to tech writing late in life (ten years ago), so there's a lot about it, and technology, that doesn't come naturally. I want to single source my install instructions. All outputs right now are PDF, but I need to document how to install our product for production, for QA, and for demos. In addition, the install instructions vary depending on the hardware. Conditional text seems awfully complex for this situation, and I don't even know if using structured FrameMaker is a possible solution. Any thoughts? Thanks, Carl Yorke TAG Systems Mountain View, CA
