This was presented as part of Neil Perlin's Bleeding Edge session at STC Summit 2014. It is for tech writers who need to publish their Adobe FrameMaker content into a Salesforce Knowledge knowledgebase.
What Are The Drone Anti-jamming Systems Technology?
Putting it where they need it: How to Populate a Salesforce Knowledge base with FrameMaker content
1. Putting it WhereThey Need It
Publishing FrameMaker-Sourced Content
into a SalesForce Knowledgebase
2. I’m John Sgammato
• Documentation architect at Actifio, previously
Imprivata, CoreChange, and Genetic
MicroSystems/Affymetrix
• You might see me in: STC New England Chapter, STC
LoneWriters SIG, the Framers list, and some LinkedIn
• I specialize in hi-tech start-ups
• That means I have to build everything myself…
• …and adapt to whatever other systems are put in place
without my consultation.
3. Support Doesn’t Use My Doc!
I see this a lot:
• Support MUST use Salesforce for customer issue
tracking
• Salesforce provides a “knowledgebase tool”, so they
work with that, building it themselves.
• But they don’t do a good job.They end up with a
knowledge base with no knowledge in it, baffling users.
• What they really need is my hundreds of ENG-reviewed
procedures in their knowledgebase.
4. So I’ll Put My Doc into Salesforce!
• Well, that’s easier said than done…
• The tool is Salesforce Knowledge (plus Chatter if you can
get it)
• There’s no “Salesforce” or “Knowledge” file format
• RoboHelp is no help – actually, nothing is
• Salesforce erects its own hurdles, like the 10MB limit
• With good reason; it’s a complex tool
5. About Salesforce
• Salesforce is Huge, and there are major stakeholders in
your company with no interest in your worthy project.
• They have new knowledgebase: Salesforce Knowledge.
• It’s in the Cloud.They upgrade you on their schedule.
• You must have help from your Salesforce Admin.
• This requires resources, and brings benefits.
• You can pitch this vision:
We can make our good Engineering-reviewed content
available to customers and support, with role-based
access and proper version control. Chatter enables
crowdsourcing.
6. WhatYou Need
• FrameMaker: I used FM11 (unstructured), other versions
should work, structure may work
• FrameScript + a small suite of scripts
• Mif2Go + config files
• Salesforce Knowledge
• Documentation
7. FrameMaker Gotchas
By clean, well-formed, and HTML-friendly, I mean:
• No index,ToC, title page and other unneeded files
• Consistent para, char, and x-ref styles
• No unresolved x-refs or text insets
• X-refs without page numbers or chapter numbers
• Consistent conditional text
• No multiple images sharing an image frame
• No two identical titles
9. The Incredible Mif2Go
Mif2Go makes export-quality XHTML, HTML, RTF, etc
• Do not use the FM export – it is essentially deprecated
• Mif2Go has great support on the Framers email list
• Mif2Go uses a few config files that you must edit
• It has almost no error-checking – do it right or fail
• Experience is your only teacher
• You can use my config files
10. Here We Go!
Here’s the Procedure:
1. Set Up the Folder Structure
2. Prepare the FM Files
3. Run Mif2Go
4. Run the FrameScripts
5. Import into Salesforce Knowledge
6. Publish to Users
11. 1. Set Up the Folder Structure
Mif2Go relies on config files that point to specific folders.
They can be confusing, so you must set them up right.
• Unzip Project.ZIP at C:
• C:Project _m2xhtml.ini, and the .prj project file
_config – html_doc.ini
images – referenced images from the FM book
scripts – the FrameScript scripts
12. Geography and Naming are Important
Use this structure with these names:
C:Project
_config
html_doc.ini………....Do nothing here
images ……………………..images for the FM docs
ReadyForImport …………Your finished files go here
scripts……………………….Do nothing here
ToBeProcessed …………..Your working files go here
OnlineTemplate.fm
<FM doc that you are processing>
13. 2. Prepare the FM Files
This makes your content HTML-friendly and robust.
1. Install and run the ArchiveFM script on your source FM project
and use the files from the ZIP.This deletes unused images.
2. Delete theTOC and the IX from the book, and theTitle Page if
there is one. Update the book.
3. Search for unresolved X-Refs and resolve them. Make sure all
images are in the same images folder.
4. Select all files in the book and run the TidyImport script to import
para, char, x-ref, condition formats & page layouts from
OnlineTemplate.fm. NOTVariables! Update and resolve issues.
Don’t worry about inconsistent page numbering. Save and close.
5. Copy the FM files to C:Project and the referenced images to
C:Projectimages. Reopen the book to update the links.
14. 3. Use Mif2Go to Generate Good XHTML
1. In the FrameMaker book file menu, click Set Up Mif2Go
Export and select XHTML.This opens up _m2xhtml.ini.
2. In _m2xhtml.ini [Setup], change FileSuffix=xhtml to =html.
3. In _m2xhtml.ini [Setup], make 3 edits: PrjFileName,
ProjectName, and FrameBook with the name of the book
file.Then edit [HTMLOptions]Title= with the human name
for this content. Save _m2xhtml.ini.
4. Select the book file. In the FM File menu, select Save Using
Mif2Go.The Choose Project dialog appears. Click OK.The
Mif2Go Export dialog appears. Click OK to run the XHTML
project.This will take a few minutes. Wait for the chime and
the little Mif2Go finished creating files dialog.
15. 4. FrameScript: Build the CSV and the ZIP
1. Open the FrameMaker book.You do not need to open the
chapters. From the FrameScript menu, run the _RunMe
script.
2. Enter your Project name (the book file name) a Data
Category (typically the version) and the Component (a
keyword that Salesforce is configured to use for this
content). For _wrap folder, navigate to the _wrap folder.
3. Click OK.This creates a ZIP and a new folder called
ImportToSalesForce_Project
4. (You can delete everything in Project folder except _config,
scripts, and _m2xhtml.ini, and copy in the next book.)
17. 5. Import the ZIP into Salesforce
• This is a primitive tool!
• There is a hard limit of 10MB for the finished ZIP file.
• Upload ImportToSalesForce_Project to SalesForce
Knowledge. Log in as admin. In the upper right corner
under your name select Setup. Navigate to Administer
> Data Management > Import Articles. Scroll down to
the importer tool. Select Procedure and then browse to
the ZIP file, then click Import Now.
18. 6. Publish toYour Users
• Under +, select Article Management.
• View the files, test them, and then publish them.