Conditional content - what do you do with it?

[magk -at- mindspring -dot- com]

I use Flare and have created multiple conditions. I know what you mean about mixing colors. Have you thought about creating a master condition that incorporates 2 or more of the other conditions?

In Flare, you can specify targets for Word, PDF, WebHelp output and include multiple conditions in the target. You can also use the same condition in multiple targets.

Hope this helps,
Gina
>
>Message: 20
>Date: Mon, 10 May 2010 16:50:21 -0400
>From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
>Subject: Conditional content - what do you do with it?
>To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
>Message-ID:
>	<D1E2C829C5011E4A84DAF8A184DD7CDA971F7A68 -at- BEL1EXCH02 -dot- amer -dot- sfnt -dot- local>
>Content-Type: text/plain; charset="us-ascii"
>
>Back in the day, I used conditions in simple ways in FrameMaker. 
>
>More recently, but still several years ago, I used conditional  
>text in RoboHelp, and started getting a little fancy with it. 
>
>That eventually bit me in the butt, and necessitated a huge 
>amount of work in a short time to fix, to my satisfaction. 
>So I began easing myself out of the use of conditions, 
>even as I was switching from RH to Flare as my HAT. 
>
>Even so, I still had conditions in place, especially in 
>help sets that had not been updated in a while. 
>
>While I found that I could trust conditions to behave as 
>expected in Flare, I still found the other problem that had 
>annoyed me. Both RH (as I recall....) and Flare use colored 
>cross-hatching on text, and colored icons in ToCs and file 
>lists, to show where a given condition is applied. 
>
>When text is given one or two conditions, that's manageable, 
>but when a block of text might have four or more cross-hatchings 
>applied to parts or all, it becomes visual mush. 
>
>My color perception is reasonably good; I can always pick 
>out the 'hidden' numbers and letters in the tests. 
>I'm not officially visually handicapped - I just have "the 
>biggest honkin' floaters <my ophthalmologist has> seen in 
><his> twenty years of practice!" - but still, I find that 
>the visual clutter can be daunting. Makes reviewing 
>and editing a misery. But part of an editing pass is to 
>determine/confirm which bits should be included/excluded in 
>this-or-that circumstance. So some of my topics are 
>about as easy to read in WYSIWYG source as are government 
>documents that have gone through... ahem... redaction.
>Makes ransom notes easy on the eyes, by comparison. 
>
>Maybe that's just me.
>
>So what is the experience of others, and what do you 
>normally do with conditions? Do you allow them to 
>overlay? Do you break out text-and-illustrations to a 
>new page or snippet as soon as it looks like more than 
>one or two conditions might need applying if the content 
>remained on the original parent page? 
>
>Other? 
>
>For that matter, how is conditional text/content 
>depicted in the interface of HATs other than RH and 
>Flare? 
>
>I find that after you've hit three layers of colored 
>cross-hatching, you are pretty much looking at brown. 
>But then, that's what I said about the curtain material 
>my wife picked out "It's got this bit of gold to pick 
>up this accessory, and this thin red stripe to pick up 
>the furniture fabric and that other little stripe to 
>catch the painting behind the sofa ..."  
>"But Dear, from more than three feet away, it all 
>looks brown to me."  
>"Brown!?  That's what you say about tweed - 'it 
>all looks grey' to you.   
>"Well, yeah. It could have a million colors in it, 
>but step back ten feet and every tweed jacket and 
>skirt in the world is grayish brown... or brown-ish 
>gray."      :-)
>
>What works out there? For HATs and conditions, I 
>mean, not fabric selection. 
>
>How small a unit do you conditionalize? 
>Do you actually go within-page to apply conditions 
>on chunks of text, or do you confine your conditions 
>to the topic-page-file level?
>
>I feel that I should be getting much more use and 
>convenience out of the conditional feature. 
>One of the product lines that I document has five 
>major products that share a good 30 percent of 
>their content globally, while several pairs within 
>the group would have as much as 70-percent commonality.
>
>
>Kevin McLauchlan
>Senior Technical Writer
>SafeNet, Inc.
>--
>
>The information contained in this electronic mail transmission 
>may be privileged and confidential, and therefore, protected 
>from disclosure. If you have received this communication in 
>error, please notify us immediately by replying to this 
>message and deleting it from your computer without copying 
>or disclosing it.
>
>
>
>
>------------------------------
>
>Message: 21
>Date: Mon, 10 May 2010 16:09:05 -0500
>From: Rick Stone <rstone75 -at- kc -dot- rr -dot- com>
>Subject: Re: Conditional content - what do you do with it?
>To: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
>Cc: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
>Message-ID: <4BE875F1 -dot- 2090106 -at- kc -dot- rr -dot- com>
>Content-Type: text/plain; charset=ISO-8859-1; format=flowed
>
>Hi Kevin
>
>I know you say you are using Flare, but perhaps it has a feature similar 
>to RoboHelp. In RoboHelp you have an ability to turn off the cross hatch 
>shading. Perhaps Flare offers a similar feature?
>
>Cheers... Rick :)
>
>McLauchlan, Kevin wrote:
>> Back in the day, I used conditions in simple ways in FrameMaker. 
>>
>> More recently, but still several years ago, I used conditional  
>> text in RoboHelp, and started getting a little fancy with it. 
>>
>> That eventually bit me in the butt, and necessitated a huge 
>> amount of work in a short time to fix, to my satisfaction. 
>> So I began easing myself out of the use of conditions, 
>> even as I was switching from RH to Flare as my HAT. 
>>
>> Even so, I still had conditions in place, especially in 
>> help sets that had not been updated in a while. 
>>
>> While I found that I could trust conditions to behave as 
>> expected in Flare, I still found the other problem that had 
>> annoyed me. Both RH (as I recall....) and Flare use colored 
>> cross-hatching on text, and colored icons in ToCs and file 
>> lists, to show where a given condition is applied. 
>>
>> When text is given one or two conditions, that's manageable, 
>> but when a block of text might have four or more cross-hatchings 
>> applied to parts or all, it becomes visual mush. 
>>
>> My color perception is reasonably good; I can always pick 
>> out the 'hidden' numbers and letters in the tests. 
>> I'm not officially visually handicapped - I just have "the 
>> biggest honkin' floaters <my ophthalmologist has> seen in 
>> <his> twenty years of practice!" - but still, I find that 
>> the visual clutter can be daunting. Makes reviewing 
>> and editing a misery. But part of an editing pass is to 
>> determine/confirm which bits should be included/excluded in 
>> this-or-that circumstance. So some of my topics are 
>> about as easy to read in WYSIWYG source as are government 
>> documents that have gone through... ahem... redaction.
>> Makes ransom notes easy on the eyes, by comparison. 
>>
>> Maybe that's just me.
>>
>> So what is the experience of others, and what do you 
>> normally do with conditions? Do you allow them to 
>> overlay? Do you break out text-and-illustrations to a 
>> new page or snippet as soon as it looks like more than 
>> one or two conditions might need applying if the content 
>> remained on the original parent page? 
>>
>> Other? 
>>
>> For that matter, how is conditional text/content 
>> depicted in the interface of HATs other than RH and 
>> Flare? 
>>
>> I find that after you've hit three layers of colored 
>> cross-hatching, you are pretty much looking at brown. 
>> But then, that's what I said about the curtain material 
>> my wife picked out "It's got this bit of gold to pick 
>> up this accessory, and this thin red stripe to pick up 
>> the furniture fabric and that other little stripe to 
>> catch the painting behind the sofa ..."  
>> "But Dear, from more than three feet away, it all 
>> looks brown to me."  
>> "Brown!?  That's what you say about tweed - 'it 
>> all looks grey' to you.   
>> "Well, yeah. It could have a million colors in it, 
>> but step back ten feet and every tweed jacket and 
>> skirt in the world is grayish brown... or brown-ish 
>> gray."      :-)
>>
>> What works out there? For HATs and conditions, I 
>> mean, not fabric selection. 
>>
>> How small a unit do you conditionalize? 
>> Do you actually go within-page to apply conditions 
>> on chunks of text, or do you confine your conditions 
>> to the topic-page-file level?
>>
>> I feel that I should be getting much more use and 
>> convenience out of the conditional feature. 
>> One of the product lines that I document has five 
>> major products that share a good 30 percent of 
>> their content globally, while several pairs within 
>> the group would have as much as 70-percent commonality.
>
>
>------------------------------
>
>Message: 22
>Date: Mon, 10 May 2010 22:37:03 +0100
>From: "Stuart Conner" <work -at- stuartconner -dot- me -dot- uk>
>Subject: RE: Reusing/Managing Requirements Across Multiple Projects
>To: "'Leonard C. Porrello'" <Leonard -dot- Porrello -at- SoleraTec -dot- com>,
>	<techwr-l -at- lists -dot- techwr-l -dot- com>
>Message-ID: <000501caf088$ee282fb0$ca788f10$ -at- me -dot- uk>
>Content-Type: text/plain;	charset="us-ascii"
>
>"So what you basically want is a comprehensive requirements tracking system
>that enables you to view any given requirement as it occurs in any and all
>projects/models ..."
>
><<< Yes - but to be clear, to be able to see the usage of multiple
>requirements at a time rather than being able to see the usage of only one
>requirement at a time. >>>
>
>"...and all dependencies related to that requirement ..."
>
><<< Haven't been concerned with dependencies between requirements up until
>now, if that is what you mean. >>>
>
>"...and, I assume, the ability to create custom tailored reports?"
>
><<< Ideally yes, but being able to view/edit/manage the requirements is more
>important. If I had to export the data back to Excel (for example) to
>produce reports, that would not be a deal breaker. >>>
>
>Stuart
>
>
>
>
>------------------------------
>
>Message: 23
>Date: Mon, 10 May 2010 17:40:21 -0400
>From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
>Subject: RE: Conditional content - what do you do with it?
>To: Rick Stone <rstone75 -at- kc -dot- rr -dot- com>
>Cc: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
>Message-ID:
>	<D1E2C829C5011E4A84DAF8A184DD7CDA971F7B04 -at- BEL1EXCH02 -dot- amer -dot- sfnt -dot- local>
>Content-Type: text/plain; charset="us-ascii"
>
>
>> -----Original Message-----
>> From: Rick Stone [mailto:rstone75 -at- kc -dot- rr -dot- com] 
>> Sent: Monday, May 10, 2010 5:09 PM
>> To: McLauchlan, Kevin
>> Cc: techwr-l -at- lists -dot- techwr-l -dot- com
>> Subject: Re: Conditional content - what do you do with it?
>> 
>> Hi Kevin
>> 
>> I know you say you are using Flare, but perhaps it has a 
>> feature similar 
>> to RoboHelp. In RoboHelp you have an ability to turn off the 
>> cross hatch 
>> shading. Perhaps Flare offers a similar feature?
>> 
>> Cheers... Rick :)
>
>
>Oh yeah.  But as I say, many times I'm looking at 
>a page to review/revise where it fits into the 
>general scheme, so I'd want it turned on. 
>
>
>I'm not the most disciplined editor. I'll 
>have a certain reason in mind for going over 
>a selection of topics, but if I spot something 
>else that needs changing, or if something reminds 
>me of something else I should add/change, then 
>I'll probably do it on the spot. 
>
>Granted I could write myself a note, giving the 
>reason for the update, the location, the content... 
>but then, unless it'll be quite lengthy, I might 
>just as well do it while I'm there, before I get 
>back to the original editorial task. 
>
>I've thinned out many of the layered conditions, 
>but at the cost of introducing duplicate text in 
>a lot of places. But there are still some ugly 
>multi-condition left-overs. When I encounter them, 
>I need to do something about them, so the conditions 
>need to be visible to remind me to do that.
>
>
>It'll all even out once I've gone entirely to a better 
>way of blocking out my use of conditions. 
>
>But now's a good time to hear from others who make 
>good use of more than one or two in a project. 
>
> - K
>
>
>The information contained in this electronic mail transmission 
>may be privileged and confidential, and therefore, protected 
>from disclosure. If you have received this communication in 
>error, please notify us immediately by replying to this 
>message and deleting it from your computer without copying 
>or disclosing it.
>
>
>
>
>------------------------------
>
>Message: 24
>Date: Tue, 11 May 2010 00:57:52 +0300
>From: SB <sylvia -dot- braunstein -at- gmail -dot- com>
>Subject: Re: Seapine Surround for User Documentation Source Control
>To: cjcbrown -at- comcast -dot- net
>Cc: Techshoret <techshoret -at- yahoogroups -dot- com>,	TECHWR-L Whirlers
>	<techwr-l -at- lists -dot- techwr-l -dot- com>
>Message-ID:
>	<AANLkTimQJVl4LWKLN52lPGFasbnF25fYJfrkiKzATwm3 -at- mail -dot- gmail -dot- com>
>Content-Type: text/plain; charset=ISO-8859-1
>
>Thanks to all for your insightful answers.
>
>On Mon, May 10, 2010 at 8:44 PM, <cjcbrown -at- comcast -dot- net> wrote:
>
>>  Hi Sylvia,
>>
>>
>>
>> We are a software company delivering product documentation in PDF, webhelp,
>> and html.
>>
>> Most of our source files are in Framemaker and the help is being moved to
>> Flare.
>>
>>
>>
>> We have available to us the software version control system and SharePoint
>> also.
>>
>>
>>
>> As to official version control, we made the decision long ago not to use
>> version control on Frame files.
>>
>> As someone has mentioned, the space needs for diffs are huge and the ROI
>> for tool and process time and cost was not there we thought.
>>
>> We use simple saves and backup to the network file system and for 15 years
>> this has been sufficient for all needs
>>
>> including the occasional fire drill with restoring earlier versions.  But,
>> we do not have much context sensitive help,
>>
>> that might make a difference.
>>
>>
>>
>> If, for something like ISO compliance, we needed to do version control on
>> document source files,
>>
>> I would do text version of the sources, like XML from Flare or MIF for
>> clunky old Frame.
>>
>> I would test first to see if I could save as text files, check in, then
>> check out and recreate the project.
>>
>> Basically as little as possible to meet source code requirements.
>>
>> And then there is the whole issue of doing diffs on 100+ PNG screen
>> shots... per release.
>>
>>
>>
>> We use SharePoint as a repository for finished deliverables stored item by
>> item.
>>
>> Way too clunky as check-in and check-out for multiple files
>>
>> at least how we see it here; maybe your site has figured out a way to
>> handle mass quantities of files easier.
>>
>>
>>
>> We want to keep it simple.
>>
>> Multiple repositories and processes for writer deliverables can really suck
>> the time away from content.
>>
>>
>>
>> Connie
>>
>>
>>
>>
>> ----- Original Message -----
>> From: "SB" <sylvia -dot- braunstein -at- gmail -dot- com>
>> To: "TECHWR-L Whirlers" <techwr-l -at- lists -dot- techwr-l -dot- com>, "Techshoret" <
>> techshoret -at- yahoogroups -dot- com>
>> Sent: Sunday, May 9, 2010 12:03:05 PM GMT -08:00 US/Canada Pacific
>> Subject: Seapine Surround for User Documentation Source Control
>>
>>  Hi,
>>
>> I am working for a software company. I would like to organized the
>> documentation and maintain it in a source control tool. We have both
>> Seapine
>> Surround and Microsoft SharePoint.
>>
>> Part of our documentation is maintained in MS Word, the other part is
>> maintained in Author-it with Word and PDF as outputs. At some point, we
>> will
>> also have HTMLs.
>>
>> R&D wants the product documentation in Surround under the same tree as the
>> code, per version. This allows them to take snapshots. I have no problem
>> with that but I would like my PDFs and HTMLs together with my final (GA)
>> release but they do not want outputs in there, claiming that the release is
>> a different process, which means that I will have to store the PDFs and
>> HTMLs elsewhere.
>>
>> They also want the rest of the company documentation (for example special
>> projects) to be maintained in another system (SharePoint) since it is not
>> product-related.
>> I was hoping to centralize all the documentation but I see that this is
>> getting very complicated.
>>
>> I would like to know if any of you has used Seapine Surround for source
>> control. I am just wondering if Surround is the right tool for
>> documentation
>> maintenance.
>> I also wonder how software companies are managing their documentation.
>>
>> Your feedback is much appreciated,
>>
>> Many thanks,
>>
>> Sylvia
>> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>
>> Use Doc-To-Help's XML-based editor, Microsoft Word, or HTML and
>> produce desktop, Web, or print deliverables. Just write (or import)
>> and Doc-To-Help does the rest. Free trial: http://www.doctohelp.com
>>
>>
>>  - Use this space to communicate with TECHWR-L readers -
>>    - Contact admin -at- techwr-l -dot- com for more information -
>>
>>
>> ---
>> You are currently subscribed to TECHWR-L as cjcbrown -at- comcast -dot- net -dot- 
>>
>>
>> To unsubscribe send a blank email to
>> techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
>> or visit
>> http://lists.techwr-l.com/mailman/options/techwr-l/cjcbrown%40comcast.net
>>
>>
>>
>> To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
>>
>> Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
>> http://www.techwr-l.com/ for more resources and info.
>>
>> Please move off-topic discussions to the Chat list, at:
>> http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat
>>
>>
>
>
>------------------------------
>
>Message: 25
>Date: Mon, 10 May 2010 15:36:38 -0700
>From: "Leonard C. Porrello" <Leonard -dot- Porrello -at- SoleraTec -dot- com>
>Subject: RE: Conditional content - what do you do with it?
>To: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>,
>	<techwr-l -at- lists -dot- techwr-l -dot- com>
>Message-ID:
>	<0C8F3D44D4B5134D964EC1AA5F1EE7711C6EA0 -at- clark -dot- esc -dot- soleratec -dot- com>
>Content-Type: text/plain;	charset="us-ascii"
>
>Like other HATs, Help & Manual(H&M) enables you to conditionally include
>and exclude whole topics as well as text. What content is included or
>excluded depends on what conditions you have selected in your manual
>build or build script.
>
>Page properties for individual pages display in which builds a page is
>included, and you can set conditional tags for several pages
>simultaneously. For text, H&M uses tags to denote conditional text, and
>the text itself is never effaced in any way. It features IF, IFNOT,
>ELSE, and ENDIF tags. Included in the tag is the name of the condition.
>For example, <IF INSTALLGUIDE>This is text that is conditionally
>included only when the INSTALLGUIDE condition is selected for a
>build.<ENDIF> You can also have multiple includes. For example, <IF
>INSTALLGUIDE,ADMINGUIDE,EVALGUIDE>This is text that is conditionally
>included when INSTALLGUIDE _AND/OR_ ADMINGUIDE _AND/OR_ EVALGUIDE
>conditions are selected for a build.<ENDIF> You can also create
>conditional tags that include or exclude text only when several
>conditions are met. For example, <IF INSTALLGUIDE><IF ADMINGUIDE>This is
>text that is conditionally included only when INSTALLGUIDE _AND_
>ADMINGUIDE conditions are selected for a build.<ENDIF><ENDIF>.
>
>H&M includes several default built in conditions (HTML Help, Web Help,
>PDF, etc.) and enables the user to create as many custom conditions as
>he needs.
>
>You can tag individual words (or even characters) within paragraphs.
>However, this isn't recommended if there is any chance that your docs
>will need to be translated. My docs probably will need to be translated,
>so where I previously had cleverly constructed sentences with certain
>words omitted from various builds, I now generally have parallel
>sentences (and, in some cases, parallel paragraphs).
>
>>From a single source, I build several guides in Web Help and PDF for
>five different but overlapping products.
>
>Leonard
>
>
>
>-----Original Message-----
>From: techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- com
>[mailto:techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- c
>om] On Behalf Of McLauchlan, Kevin
>Sent: Monday, May 10, 2010 1:50 PM
>To: techwr-l -at- lists -dot- techwr-l -dot- com
>Subject: Conditional content - what do you do with it?
>
>Back in the day, I used conditions in simple ways in FrameMaker. 
>
>More recently, but still several years ago, I used conditional  
>text in RoboHelp, and started getting a little fancy with it. 
>
>That eventually bit me in the butt, and necessitated a huge 
>amount of work in a short time to fix, to my satisfaction. 
>So I began easing myself out of the use of conditions, 
>even as I was switching from RH to Flare as my HAT. 
>
>Even so, I still had conditions in place, especially in 
>help sets that had not been updated in a while. 
>
>While I found that I could trust conditions to behave as 
>expected in Flare, I still found the other problem that had 
>annoyed me. Both RH (as I recall....) and Flare use colored 
>cross-hatching on text, and colored icons in ToCs and file 
>lists, to show where a given condition is applied. 
>
>When text is given one or two conditions, that's manageable, 
>but when a block of text might have four or more cross-hatchings 
>applied to parts or all, it becomes visual mush. 
>
>My color perception is reasonably good; I can always pick 
>out the 'hidden' numbers and letters in the tests. 
>I'm not officially visually handicapped - I just have "the 
>biggest honkin' floaters <my ophthalmologist has> seen in 
><his> twenty years of practice!" - but still, I find that 
>the visual clutter can be daunting. Makes reviewing 
>and editing a misery. But part of an editing pass is to 
>determine/confirm which bits should be included/excluded in 
>this-or-that circumstance. So some of my topics are 
>about as easy to read in WYSIWYG source as are government 
>documents that have gone through... ahem... redaction.
>Makes ransom notes easy on the eyes, by comparison. 
>
>Maybe that's just me.
>
>So what is the experience of others, and what do you 
>normally do with conditions? Do you allow them to 
>overlay? Do you break out text-and-illustrations to a 
>new page or snippet as soon as it looks like more than 
>one or two conditions might need applying if the content 
>remained on the original parent page? 
>
>Other? 
>
>For that matter, how is conditional text/content 
>depicted in the interface of HATs other than RH and 
>Flare? 
>
>I find that after you've hit three layers of colored 
>cross-hatching, you are pretty much looking at brown. 
>But then, that's what I said about the curtain material 
>my wife picked out "It's got this bit of gold to pick 
>up this accessory, and this thin red stripe to pick up 
>the furniture fabric and that other little stripe to 
>catch the painting behind the sofa ..."  
>"But Dear, from more than three feet away, it all 
>looks brown to me."  
>"Brown!?  That's what you say about tweed - 'it 
>all looks grey' to you.   
>"Well, yeah. It could have a million colors in it, 
>but step back ten feet and every tweed jacket and 
>skirt in the world is grayish brown... or brown-ish 
>gray."      :-)
>
>What works out there? For HATs and conditions, I 
>mean, not fabric selection. 
>
>How small a unit do you conditionalize? 
>Do you actually go within-page to apply conditions 
>on chunks of text, or do you confine your conditions 
>to the topic-page-file level?
>
>I feel that I should be getting much more use and 
>convenience out of the conditional feature. 
>One of the product lines that I document has five 
>major products that share a good 30 percent of 
>their content globally, while several pairs within 
>the group would have as much as 70-percent commonality.
>
>
>Kevin McLauchlan
>Senior Technical Writer
>SafeNet, Inc.
>--
>
>The information contained in this electronic mail transmission 
>may be privileged and confidential, and therefore, protected 
>from disclosure. If you have received this communication in 
>error, please notify us immediately by replying to this 
>message and deleting it from your computer without copying 
>or disclosing it.
>
>
>^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
>Use Doc-To-Help's XML-based editor, Microsoft Word, or HTML and 
>produce desktop, Web, or print deliverables. Just write (or import) 
>and Doc-To-Help does the rest. Free trial: http://www.doctohelp.com
>
>
> - Use this space to communicate with TECHWR-L readers - 
>   - Contact admin -at- techwr-l -dot- com for more information - 
>
>
>---
>You are currently subscribed to TECHWR-L as
>Leonard -dot- Porrello -at- soleratec -dot- com -dot- 
>
>To unsubscribe send a blank email to 
>techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
>or visit
>http://lists.techwr-l.com/mailman/options/techwr-l/leonard.porrello%40so
>leratec.com
>
>
>To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
>
>Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
>http://www.techwr-l.com/ for more resources and info. 
>
>Please move off-topic discussions to the Chat list, at:
>http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat
>
>
>
>------------------------------
>
>Message: 26
>Date: Mon, 10 May 2010 16:30:57 -0700
>From: "Leonard C. Porrello" <Leonard -dot- Porrello -at- SoleraTec -dot- com>
>Subject: RE: Context-sensitive - menu-item topic or... Clippy?
>To: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>,
>	<techwr-l -at- lists -dot- techwr-l -dot- com>
>Message-ID:
>	<0C8F3D44D4B5134D964EC1AA5F1EE7711C6EA2 -at- clark -dot- esc -dot- soleratec -dot- com>
>Content-Type: text/plain;	charset="us-ascii"
>
>>How do you handle this when you hit optional stuff? 
>>Material that the user/administrator could CHOOSE to do/not-do or
>do-one->way/do-another-way...
>
>>We also have product variants that are pre-set in the factory, and
>which >then affect how many things are done.
>
>For optional stuff, I either include it as a tip or have an expandable
>section. Whether I use or tip or expandable section depends on the
>weight of the alternative. Meaning, if the alternative is of "the road
>less traveled," I would include it as a tip (featuring my own pretty
>"tip" icon). For example, "To eliminate flying monkeys en masse, simply
>pour water upon the Wicked Witch of the West. Tip: if you'd rather
>dispatch flying monkeys one at a time, you can do so using the aluminum
>baseball bat bundled with your product."
>
>When an alternatives are equally viable and possibly desirable, I use
>expandable text. For example, "There are three ways to prevent Little
>Bunny Foo Foo from bonking field mice on the head: Way 1: Appeal to his
>better nature; Way 2: Threaten to turn him into a goat; Way 3: Show him
>your grandmother's recipe for Hasenpfeffer. Choose the option you prefer
>below." Of course, it would all be nicely formatted and bulleted.
>
>For variants that are pre-set at the factory, I'd have to build new
>pages. In these pages, I would, of course, reuse as much content as
>possible. 
>
>For "multiple 'browse sequences' that might involve the same page for
>several user approaches, while other pages might be unique to just
>one-or-another browse sequence," I probably use the same technique you
>use in Flare. If we are talking a few pages, I have them folded into one
>"story" and use page level conditional tags to define what gets built
>where. Where I have several unique pages that compose an entirely unique
>workflow, I have several "stories" and use conditional tags to build
>each.
>
>Leonard
>
>-----Original Message-----
>From: McLauchlan, Kevin [mailto:Kevin -dot- McLauchlan -at- safenet-inc -dot- com] 
>Sent: Monday, May 10, 2010 1:08 PM
>To: Leonard C. Porrello; techwr-l -at- lists -dot- techwr-l -dot- com
>Subject: RE: Context-sensitive - menu-item topic or... Clippy?
>
> 
>Leonard C. Porrello [mailto:Leonard -dot- Porrello -at- SoleraTec -dot- com] said 
>a bunch of good stuff, including:
>
>> 
>> I've created my documentation to meet the needs of several types of
>> users: those who want and in-depth understanding of the entire product
>> workflow; those who want to understand the workflow for just 
>> part of the
>> product; those that want to understand just a particular 
>> field, term, or
>> concept; and those who aren't sure what exactly they need to know but
>> who are looking at a GUI and wondering WTF?
>> 
>> Our product comprises several tabbed GUIs, each responsible for some
>> part of the Information Lifecycle Management (ILM) process and
>> infrastructure. For example, one GUI defines storage vaults and media;
>> another defines data ingest polices; and another defines data movement
>> policies. To create an ILM system from scratch, the user would use
>> several different GUIs in pretty much a pre-defined order. Later, to
>> expand or modify his system, the user would employ individual GUIs as
>> needed. For example, if the user wanted to tweak just his data ingest
>> policies, he would use just the GUI dedicated to creating and managing
>> data ingest policies.
>
>We have a little of that on a smaller scale, since 
>we're dealing with a hardware product and the installation, 
>configuration, ongoing maintenance and occasional 
>adaptation of that hardware and our software that 
>goes with it. 
>
>Just reading what you have to say here gives me a nudge 
>to go back and review some of my organization and 
>bridging. 
> 
>> Within each GUI, we provide hover help and three additional help
>> options: "Table of Contents," "Overview," and "Current Page." 
>> All three
>> link to the same browser based on-line help (but in different ways).
>> "Table of Contents" links to the overview of the entire ILM workflow
>> with which the documentation begins. "Overview" links to the overview
>> section for the given GUI the user has open. This section includes an
>> overview of the workflow for the given GUI, how the GUI fits into the
>> overall product workflow, and links to specific help pages for
>> individual GUI tabs. "Current page" links to the page in the help that
>> documents the GUI tab the user is currently using. Each help page
>> includes an overview of what a user can do and why, in relation to
>> overall workflow, they'd want to do it.
>
>That's certainly clear-cut when the steps are straightforward 
>and follow from previous actions.
>
>How do you handle this when you hit optional stuff? 
>Material that the user/administrator could CHOOSE 
>to do/not-do or do-one-way/do-another-way...
>
>We also have product variants that are pre-set in the factory, 
>and which then affect how many things are done. 
>
>In the case of - say - authentication and some related 
>procedures that come up frequently, I've been a little 
>un-even. In some cases, I make a split at the page/topic 
>or section-of-ToC level - one branch for doing it one way 
>if you bought that configuration, the other branch if 
>you bought a different configuration, and then those 
>branches (multiple topic-pages) either just stop at 
>the end of each, or lead to a common "next" step where 
>a) there is a particular next step and 
>b) it has more common elements than not, thus justifying 
>  the re-merge of the 'narrative'.
>
>In other cases, I've made the split "on-page" by using 
>drop-down or expanding text.
>
>By "un-even" I mean that I didn't have a hard-and-fast 
>rule for when it made sense to simply offer a couple 
>of optional paths within a topic page and when it made 
>most sense to break out entire branches of topic sequences. 
>
> 
>> I've structured the help so that the user can understand workflow and
>> work through tasks by simply reading the TOC from top to 
>> bottom. Section
>> titles also include GUI names so that a user can browse to the section
>> for any GUI without needing a clear idea of the task they 
>> might want to
>> accomplish with that GUI.
>> 
>> In short, the help is task centric AND application centric. Along with
>> documentation for particular GUIs, tabs, and fields, it features an
>> abundance of overview and in-depth information for users who want to
>> understand the big picture. It also includes terse "How To" sections,
>> for users who want to be led through a task as quickly and 
>> painlessly as
>> possible, as well as tutorials. And of course, the help also features
>> search functionality and an index.
>
>Do you have, say, multiple "browse sequences" that might involve 
>the same page for several user approaches, while other pages might 
>be unique to just one-or-another browse sequence?  I'm using that 
>term because I'm familiar with it from RH and Flare - not sure if 
>it's how the concept is named in Author-It, Doc2Help and other HATS... 
>
>I was going to ask about conditions here, but I think that'll 
>be too much. I'll start a different thread on that. 
>
>
>
>------------------------------
>
>Message: 27
>Date: Mon, 10 May 2010 23:32:59 +0000 (UTC)
>From: cjcbrown -at- comcast -dot- net
>Subject: Re: Context-sensitive - menu-item topic or... Clippy?
>To: Kevin McLauchlan <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
>Cc: techwr-l -at- lists -dot- techwr-l -dot- com
>Message-ID:
>	<763575503 -dot- 15490051273534379511 -dot- JavaMail -dot- root -at- sz0045a -dot- emeryville -dot- ca -dot- mail -dot- comcast -dot- net>
>	
>Content-Type: text/plain; charset=utf-8
>
>
>
>>> Are your end-users actually accessible to you in some way? 
>
>I get to go with the trainer on-site when a customer is big enough to buy classroom training. Now that is fun and I literally do write down what they ask. I get to "job shadow" when they order that too. And I too ride along with new employees and watch how they learn. 
>
>>>> Or do you do what I do, constructing a composite 
>"user" (or three) from field trouble reports, Sales-Engineer 
>discussions, Apps-Eng/Engineering-Services comments 
>and discussion threads? 
>
>
>
>Yes, I do that too. 
>
>>> the engineering testers ...?aren't much help in getting a feel for what a naive 
>user requires. 
>
>
>
>Same with us. Also our development context is WAY different from the customer's context in using the product. 
>
>
>
>Sometimes I can get naive-user equivalents 
>
>by having a fellow employee at another site, remotely look at the software. 
>
>
>
>I would like to remotely comment on software with our customers, but they are so big and formal 
>
>that there has to be a Statement of Work and NDAs to have the smallest simplest contact outside of training ... so, too bad for me. 
>
>> From that, we derive the "top user tasks" that people have questions about, that are not obvious in the software. 
>
>>> we are constantly learning new "top user?tasks" as our products enter new and varied markets. 
>
>
>
>Us too, and some new tasks ?change earlier tasks, forcing rewrites. 
>
>>> But of course, you also have ToC, glossary, Index, and Search 
>
>
>
>yup, sorry didn't spell those out 
>
>>> I wonder if all classes of user-customers would agree on what is "obvious". 
>
>
>
>Ours do not agree on what's obvious. But if anyone in any audience?has asked, we put it in. If no one has asked, we have to be persuaded... 
>
>>> But we also sell to developers 
>
>
>
>Us too, and the developers are so different an audience that they get different deliverables.????????? 
>
>>> Is anybody doing that now? ?Producing "generic" 
>help for your product, but assisting your big 
>customers to adapt/integrate that help into the 
>larger Help that they provide for their product 
>(of which your product then becomes a component...) ?? 
>
>
>Not really, but a couple of our products talk about how to insert customer's own stuff into the help at certain places.? 
>
>One customer rewrites individual HTML topics.? And another customer adds links to his own docs in the same list as docs we produce. 
>
>
>
>Connie
>
>------------------------------
>
>Message: 28
>Date: Tue, 11 May 2010 09:43:50 +1000
>From: Janice Gelb <janice -dot- gelb -at- oracle -dot- com>
>Subject: Re: Fwd: NEWS: MSTP makes the switch: email and website
>	nowhyphenless
>To: techwr-l List <techwr-l -at- lists -dot- techwr-l -dot- com>
>Message-ID: <4BE89A36 -dot- 7030905 -at- oracle -dot- com>
>Content-Type: text/plain; charset=windows-1252; format=flowed
>
>On  Apr 29, 2010 9:50PM, punit shrivastava wrote:
>>
>>> From the mailing list for the Information Design&  Architecture SIG of the
>> STC
>>
>> This just came in from a source at Microsoft... [snip]
>>
>> *website*
>>
>> -  Write *website* and *webpage* as one word; all other
>> two-word web terms remain as two words.
>>
>
>Twitter update from FakeAPStylebook: "When referring
>to Spider-Man, "Web head" can now be written as
>"webhead."
>
>:->
>
>-- Janice
>
>**************************************************************
>Janice Gelb             | The only connection Oracle has with
>janice -dot- gelb -at- oracle -dot- com  | this message is the return address
>
>
>------------------------------
>
>Message: 29
>Date: Tue, 11 May 2010 10:05:44 +1000
>From: Janice Gelb <janice -dot- gelb -at- oracle -dot- com>
>Subject: Re: Context-sensitive - menu-item topic or... Clippy?
>To: techwr-l -at- lists -dot- techwr-l -dot- com
>Message-ID: <4BE89F58 -dot- 5070702 -at- oracle -dot- com>
>Content-Type: text/plain; charset=UTF-8; format=flowed
>
>On  May 11, 2010 3:59AM, cjcbrown -at- comcast -dot- net wrote:
>>
>> I loved your writeup of Clippy.
>>
>
>You can make your own Clippy message at this site:
>
>http://www.imagegenerator.net/create/clippy/
>
>Although it would be hard to beat this classic:
>
>http://is.gd/c3rL1
>
>--Janice
>
>**************************************************************
>Janice Gelb             | The only connection Oracle has with
>janice -dot- gelb -at- oracle -dot- com  | this message is the return address
>
>
>------------------------------
>
>_______________________________________________
>You are currently subscribed to 
>TECHWR-L.
>To unsubscribe send a blank email to 
>http://lists.techwr-l.com/mailman/listinfo/techwr-l
>Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit 
>http://www.techwr-l.com/ for more resources and info.
>
>End of TECHWR-L Digest, Vol 55, Issue 10
>****************************************



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use Doc-To-Help's XML-based editor, Microsoft Word, or HTML and 
produce desktop, Web, or print deliverables. Just write (or import) 
and Doc-To-Help does the rest. Free trial: http://www.doctohelp.com


 - Use this space to communicate with TECHWR-L readers - 
   - Contact admin -at- techwr-l -dot- com for more information - 


---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info. 

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat