Background
I've moved a large, rapidly growing, technical documentation project into Flare.
The authors and owners of this content are not writers; they are engineers (e.g., electrical, construction, design, architectural, operations, network).
My function as the writer/editor on the project is to review and edit engineers' changes and publish (push from Word to PDF) new versions of the doc set on a quarterly basis.
Our process and setup is evolving as the documentation set grows.
I initially set up Flare to help me manage the content.
I'm managing the doc set on SharePoint. I'm not publishing anything to HTML - it is purely a set of documentation.
Because the engineers are not writers, I set it up so they can continue to use Word to create their content.
The content is in Flare and I publish the separate Word docs to a SharePoint doc library.
The engineers go to the SharePoint library, check out the Word doc, make changes, check it back in.
I anticipated moving them to use Contributor at some point because there is still a lot I cannot control without a lot of manual intervention on my side.
Now that the project is growing, it has become clear it is time to get them to use Contributor.
Situation
I need to write a proposal/business case to convince these engineers and their leadership to purchase Contributor and use it instead of Word.
I've searched for info on how to do this and I can find very little practical advice out there.
I need something more extensive than MadCap Blog: Making the business case....
How do I convince people who aren't writers (they don't even really like writing) to use a new tool that is a significant departure than what they are currently using?
From my limited experience with Contributor, although it has similarities to Word, it appears to have a fairly steep learning curve for writers to adopt and use with proficiency; I can't even imagine what the experience would be for non-writers.
~Thanks in advance for any guidance you can offer.~
Making the Business Case for Contributor (and Flare)
-
ChoccieMuffin
- Senior Propellus Maximus
- Posts: 2632
- Joined: Wed Apr 14, 2010 8:01 am
- Location: Surrey, UK
Re: Making the Business Case for Contributor (and Flare)
We have had a similar situation, where the "master" content is maintained by non-TAs, and they use Word. The big difference between what you want to do and what we do is that we then produce a PDF output, and THAT is the deliverable, rather than Word files - for us, Word files are just the SOURCE. The reason for this is that Word and Flare don't play together very nicely, and you just can't go from Word to Flare to Word and BACK to Flare, as the styles break.
Anyway, here's what we do.
As you suggested, the SMEs want to use a tool they're familiar with (Word) rather than having the overhead of learning a new tool (plus the cost of additional Contributor or Central licences, of course). So instead of making them use a tool they're not familiar with we provide a very rigid Word template that they MUST use for any source material. This template is locked, so they can ONLY use the styles in the template and can't just change font size, add bold etc willy-nilly. This is because I have also got all the styles to use in Flare's import files locked down, so that a named style in the Word file points to a named style in the Flare project. I have TOCs, targets, import files etc all set up in Flare, including the group's stylesheet, standard text such as copyright and repeating bits and pieces. (I've even managed to get my search-and-replace scripts to the state that I can let the SMEs add conditions to stuff in their Word files but I won't go into that at this point.)
I have a PowerShell script that runs a "starter" target in my Flare project, which runs all the import files. As you know the resultant HTML from a Word import is a bit rubbish, to put it mildly (lots of inline styling even though I have prevented inline styling in the Word doc, for example), so my PS script then runs a set of search-and-replace tasks on the HTML files to clean them up. Finally, the "proper" target runs that builds a PDF from the now-clean HTML files. Our SMEs then check the resulting PDF, and if they need to make any changes, they make them in the Word document and rebuild. If they have any formatting problems they ask me. If they want to add a new chapter, they ask me (because I set all that stuff up in the Flare project). It works reasonably well despite the odd limitation, but it does mean that I don't actually DO anything in Flare for those projects.
You could investigate this as an approach if: a) PDF would be an acceptable output, and b) your SMEs would be willing to use a rigid Word template for managing the source content.
Anyway, here's what we do.
As you suggested, the SMEs want to use a tool they're familiar with (Word) rather than having the overhead of learning a new tool (plus the cost of additional Contributor or Central licences, of course). So instead of making them use a tool they're not familiar with we provide a very rigid Word template that they MUST use for any source material. This template is locked, so they can ONLY use the styles in the template and can't just change font size, add bold etc willy-nilly. This is because I have also got all the styles to use in Flare's import files locked down, so that a named style in the Word file points to a named style in the Flare project. I have TOCs, targets, import files etc all set up in Flare, including the group's stylesheet, standard text such as copyright and repeating bits and pieces. (I've even managed to get my search-and-replace scripts to the state that I can let the SMEs add conditions to stuff in their Word files but I won't go into that at this point.)
I have a PowerShell script that runs a "starter" target in my Flare project, which runs all the import files. As you know the resultant HTML from a Word import is a bit rubbish, to put it mildly (lots of inline styling even though I have prevented inline styling in the Word doc, for example), so my PS script then runs a set of search-and-replace tasks on the HTML files to clean them up. Finally, the "proper" target runs that builds a PDF from the now-clean HTML files. Our SMEs then check the resulting PDF, and if they need to make any changes, they make them in the Word document and rebuild. If they have any formatting problems they ask me. If they want to add a new chapter, they ask me (because I set all that stuff up in the Flare project). It works reasonably well despite the odd limitation, but it does mean that I don't actually DO anything in Flare for those projects.
You could investigate this as an approach if: a) PDF would be an acceptable output, and b) your SMEs would be willing to use a rigid Word template for managing the source content.
Started as a newbie with Flare 6.1, now using Flare 2023.
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
Re: Making the Business Case for Contributor (and Flare)
Thanks so much. I need to think through your process a bit to determine whether it will work in our case. I neglected to mention the final output is actually a PDF. I just went the Word route as an interim step for the source docs so the engineers wouldn't need to learn a new tool...yet. I let them know they may need to adopt the new tool in the near future.
However, your approach may work even better. Because I don't do any of the writing (only editing), I really only need Flare to manage and build the source and final files (docs and PDFs). I also use Flare to set up the Word template and build the Word source docs. That has also been another issue--the engineers 'go rogue' and whip up their own docs without using the template (or they decide not to follow the template, don't understand how to use it, change it, etc.).
There are approx. 120 chapters in total (many are just a few pages). I'm also trying to set Flare up to build individual PDFs with their own TOCs as well as a consolidated PDF with a master TOC. (both of which will be the final format of the content)
Let me see if I understand your process from a high level:
Thank you again for taking the time to respond to my post.
However, your approach may work even better. Because I don't do any of the writing (only editing), I really only need Flare to manage and build the source and final files (docs and PDFs). I also use Flare to set up the Word template and build the Word source docs. That has also been another issue--the engineers 'go rogue' and whip up their own docs without using the template (or they decide not to follow the template, don't understand how to use it, change it, etc.).
There are approx. 120 chapters in total (many are just a few pages). I'm also trying to set Flare up to build individual PDFs with their own TOCs as well as a consolidated PDF with a master TOC. (both of which will be the final format of the content)
Let me see if I understand your process from a high level:
- SMEs use a locked Word template (I assume it is locked through the 'protect document' feature in Word)
- A script creates a placeholder target and imports the Word file as HTML into Flare
- The script cleans up the HTML to align with the styles you've set up in Flare
- The final target runs on the cleaned up HTML files and builds a PDF
- SMEs review the PDF
- They make their changes in the Word doc
- You repeat the process from Step 2 to rebuild the final PDF
Thank you again for taking the time to respond to my post.
-
ChoccieMuffin
- Senior Propellus Maximus
- Posts: 2632
- Joined: Wed Apr 14, 2010 8:01 am
- Location: Surrey, UK
Re: Making the Business Case for Contributor (and Flare)
You've pretty much grasped the process, but see a bit later in this post for a bit of clarification.
As for your SMEs messing around and refusing to use the template, the buck stops with them - if they don't use the template properly, then they won't get the output they want. If they refuse to follow your instructions (my template contains 15 pages of instructions and details every single style!) then that's their lookout, and they'll end up having to do lots of extra work. You'll be able to sell the template to them, I'm sure.
It might take a few weeks to go through your existing Word docs to format them using your shiny new template, but it'll be worth it. And yes, I lock all the source documents with the "Protect" thing in Word. Not perfect but it reduces inadvertent errors.
You can do all the setting up in Flare to give you the outputs you want.
If you do any editing, do it in the Word docs - you don't need to even TOUCH the files in Flare - in fact, with my process I CAN'T touch them, as the build machine just ignores my changes.
Source files consist of Word docs (one per chapter) that the SMEs edit, and a skeleton Flare project.
The skeleton project contains targets, TOCs and import files.
One of the targets - 1_Starter - has the sole purpose of importing the source Word files.
The import files contain the information that you would normally see in a Word import file, but I've edited it in a text editor. For example in Word there's a paragraph style H2_KeepWithPrevious that maps to h2 with the generic style .KeepWithPrevious applied, and you can't do that in the Flare interface so the import file contains
<Map
From="H2_KeepWithPrevious"
To="h2.KeepWithPrevious" />
We have two levels of script - the PowerShell script that does checkouts from SVN, runs Flare and runs the search-and replace scripts; and a set of FAR scripts that do the search-and-replace operations on the HTML files (mainly) to clean up the mess that you get from a Word import. (I use FAR because my predecessor did, I'm sure you could do the same thing in other tools).
I'm under a bit of pressure to get a release ready so I don't have time to go into detail right now - just got my head out of the pit for a breather - but I'll respond more fully later in the week, if that's ok.
Before I go, here are a couple of extracts that might get you started. This is from the .flimp file (there are lots of other styles I've specified):
and here's an extract from one of my FAR files that tidies up the mess - there's LOADS more in this script (I can even convert tags in the Word doc to condition tags in Flare, but didn't want to muddy the water too much):
I'll be back later in the week, now to go and have some lunch and get my head back in the pit that is my life at the moment! Good luck.
As for your SMEs messing around and refusing to use the template, the buck stops with them - if they don't use the template properly, then they won't get the output they want. If they refuse to follow your instructions (my template contains 15 pages of instructions and details every single style!) then that's their lookout, and they'll end up having to do lots of extra work. You'll be able to sell the template to them, I'm sure.
It might take a few weeks to go through your existing Word docs to format them using your shiny new template, but it'll be worth it. And yes, I lock all the source documents with the "Protect" thing in Word. Not perfect but it reduces inadvertent errors.
You can do all the setting up in Flare to give you the outputs you want.
If you do any editing, do it in the Word docs - you don't need to even TOUCH the files in Flare - in fact, with my process I CAN'T touch them, as the build machine just ignores my changes.
Source files consist of Word docs (one per chapter) that the SMEs edit, and a skeleton Flare project.
The skeleton project contains targets, TOCs and import files.
One of the targets - 1_Starter - has the sole purpose of importing the source Word files.
The import files contain the information that you would normally see in a Word import file, but I've edited it in a text editor. For example in Word there's a paragraph style H2_KeepWithPrevious that maps to h2 with the generic style .KeepWithPrevious applied, and you can't do that in the Flare interface so the import file contains
<Map
From="H2_KeepWithPrevious"
To="h2.KeepWithPrevious" />
We have two levels of script - the PowerShell script that does checkouts from SVN, runs Flare and runs the search-and replace scripts; and a set of FAR scripts that do the search-and-replace operations on the HTML files (mainly) to clean up the mess that you get from a Word import. (I use FAR because my predecessor did, I'm sure you could do the same thing in other tools).
I'm under a bit of pressure to get a release ready so I don't have time to go into detail right now - just got my head out of the pit for a breather - but I'll respond more fully later in the week, if that's ok.
Before I go, here are a couple of extracts that might get you started. This is from the .flimp file (there are lots of other styles I've specified):
Code: Select all
<ParagraphStyles>
<Map
From="H1"
To="h1" />
<Map
From="H1_NoChapNum"
To="h1.NoChapNum" />
<Map
From="H1_Section_Heading"
To="h1.Section_Heading" />
<Map
From="H2"
To="h2" />
<Map
From="H2_KeepWithPrevious"
To="h2.KeepWithPrevious" />
<Map
From="H3"
To="h3" />
<Map
From="H3_PageBreakBefore"
To="h3.PageBreakBefore" />
<Map
From="H4"
To="h4" />
<Map
From="H4_PageBreakBefore"
To="h4.PageBreakBefore" />
<Map
From="H5"
To="h5" />
<Map
From="H6"
To="h6" />
<Map
From="BodyCodeExplained"
To="p.CodeExplained" />
<Map
From="BodyCodeLastLine"
To="p.CodeLastLine" />
<Map
From="BodyImage"
To="p.graphic" />
<Map
From="BodyImportant"
To="p.important" />
<Map
From="BodyIntro"
To="p.intro" />
<Map
From="BodyKeepWithNext"
To="p.KeepWithNext" />
<Map
From="BodyNote"
To="p.note" />
<Map
From="BodyTip"
To="p.tip" />
</ParagraphStyles>
and here's an extract from one of my FAR files that tidies up the mess - there's LOADS more in this script (I can even convert tags in the Word doc to condition tags in Flare, but didn't want to muddy the water too much):
Code: Select all
[Default]
/L:Clean_HTML_Formatting.log,2,brief
LoadHTMLFiles
TableHeaderToTHStyle
UL_Remove_Duplicated_Tags
UL_RemoveLocalFormatting
OL_RemoveLocalFormatting
LI_RemoveLocalFormatting_1
LI_RemoveLocalFormatting_2
LI_RemoveLocalFormatting_3
LI_Remove_Empty_LI_Tags
UL_Remove_EmptyUL_Tags
Join_Lists
ConvertTo_FlareVar
Remove_Strong
Fix_Bold_Text_Bug_1
Fix_Bold_Text_Bug_2
Join_Bold
Fix_Bold_Text_Bug_3
Remove_language_tag
[LoadHTMLFiles]
drop_options=HTMLFiles
DirScan=%CD%\Content
[HTMLFiles]
_opSkipDirs=1
_opSkipFiles=0
_opIncFiles=1
_opSkipDirsSL=Getting*|1|Resources|1|
_opSkipFilesSL=.css|1|.png|1|.fl*|1|.toc|1|
_opIncFilesSL=.ht*|1|
[TableHeaderToTHStyle]
FindStart='<p class="TableHeader">'
FindEnd='</p>'
Replace='<th><p>$A$</p></th>'
$A$.FindSubStrNo=1
$A$.ContainingText=
$A$.NotContainingText=
$A$.StartText=<p class="TableHeader">
$A$.EndText=</p>
$A$.IncStartEndText=n
[UL_Remove_Duplicated_Tags]
IgnoreMultiSpace=y
IgnoreCRLF=y
FindStart='</ul>$#13$$#10$<ul>'
Replace=''
[UL_RemoveLocalFormatting]
FindStart='<ul style="'
FindEnd='">'
Replace='<ul>'
[OL_RemoveLocalFormatting]
FindStart='<ol style="'
FindEnd='"'
Replace='<ol'
[LI_RemoveLocalFormatting_1]
FindStart='<li class="ListBullet" style="'
FindEnd='>'
Replace='<li class="ListBullet">'
[LI_RemoveLocalFormatting_2]
FindStart='<li class="ListBullet2" style="'
FindEnd='">'
Replace='<li class="ListBullet2">'
[LI_RemoveLocalFormatting_3]
FindStart='<li class="ListBullet3" style="'
FindEnd='">'
Replace='<li class="ListBullet3">'
[LI_Remove_Empty_LI_Tags]
IgnoreMultiSpace=y
IgnoreCRLF=y
FindStart='<li></li>'
Replace=''
[UL_Remove_EmptyUL_Tags]
IgnoreMultiSpace=y
IgnoreCRLF=y
FindStart='<ul>'
FindEnd='</ul>'
FindContains=
FindNotContains='<li*>'
Replace=''
[Join_Lists]
IgnoreMultiSpace=y
IgnoreCRLF=y
FindStart='</ul> <ul>'
FindContains=
Replace=''
[ConvertTo_FlareVar]
FindStart='[$'
FindEnd='$]'
Replace=<MadCap:variable name="Local_Data.$A$" />
$A$.FindSubStrNo=1
$A$.ContainingText=
$A$.NotContainingText=
$A$.StartText='[$'
$A$.EndText='$]'
$A$.IncStartEndText=n
[Remove_Strong]
FindStart='<b class="strong">'
Replace='<b>'
[Fix_Bold_Text_Bug_1]
IgnoreCRLF=y
IgnoreMultiSpace=y
FindStart='</p> <b>'
FindEnd='</b>'
Replace='</p><p><b>$A$</b></p>'
$A$.FindSubStrNo=1
$A$.ContainingText=
$A$.NotContainingText=
$A$.StartText='</p> <b>'
$A$.EndText='</b>'
$A$.IncStartEndText=n
[Fix_Bold_Text_Bug_2]
IgnoreCRLF=y
IgnoreMultiSpace=y
FindStart='</p><b>'
FindEnd='</b>'
Replace='</p><p><b>$A$</b></p>'
$A$.FindSubStrNo=1
$A$.ContainingText=
$A$.NotContainingText=
$A$.StartText='</p><b>'
$A$.EndText='</b>'
$A$.IncStartEndText=n
[Join_Bold]
IgnoreCRLF=y
IgnoreMultiSpace=y
FindStart='</b><b>'
Replace=''
[Fix_Bold_Text_Bug_3]
IgnoreCRLF=y
IgnoreMultiSpace=y
FindStart='<ul><b>'
FindEnd='</b></ul>'
Replace='<ul><li><b>$A$</b></li></ul>'
$A$.FindSubStrNo=1
$A$.ContainingText=
$A$.NotContainingText=
$A$.StartText='<ul><b>'
$A$.EndText='</b></ul>'
$A$.IncStartEndText=n
[Remove_language_tag]
FindStart=' xml:lang="en-gb"'
Replace=''
Started as a newbie with Flare 6.1, now using Flare 2023.
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
Re: Making the Business Case for Contributor (and Flare)
Best of luck on your upcoming release. No worries.
Thank you so much. I will take a look at the info you provided and we'll forumchat when you're available again.
Thank you so much. I will take a look at the info you provided and we'll forumchat when you're available again.
Re: Making the Business Case for Contributor (and Flare)
I am setting up something similar. I convinced my manager to include Contributor because of the ability to apply conditions to the text (and we have many - because the documents need to go out to different customers at the end of the day).
So my workflow will be:
- Create templ
So my workflow will be:
- Create templ
- ates in Flare for the SMEs to use to create new documents in Contributor.
- Import new docs into Flare and create review packages.
- When changes need to be made, the SME opens the review package and then sends it to me for editing and updating the published version.
- I then make a