The blog has moved to www.techwritingengineer.com
The Techwriting Engineer
– in the intersection between "technical" and "technical communication" –
Moved to www.techwritingengineer.com
The blog has moved to www.techwritingengineer.com
Posted in Uncategorized
Convert CSV-data to XML-files
Here’s a tool I developed that transforms CSV-data into XML-data based on a template.
You can use it to, for example:
- Create MadCap Flare snippet files
- Create topic files
- Create MadCap Flare target files
- Create MadCap Flare condition sets
- Create MadCap Flare variable sets
You can use it to convert any type of CSV-data into text files (e.g. HTML, XML, etc).
Click here to download the converter along with some sample CSV data!
Converting CSV data to XML files using a template
To convert files, you need
- A CSV-data file. You can use any text editor or save your Excel spreadsheet as a CSV file.
- An XML-template file.
Set up the CSV data
- Ensure that the CSV file has headers, because the first line in the CSV does not get converted.
- Verify which type of separator the file has (comma, semicolon, or tab)
In the example file (data.csv), the data looks like this:
Heading;Paragraph Heading A;Paragraph A Heading B;Paragraph B Heading C;Paragraph C Heading D;Paragraph D Heading E;Paragraph E Heading F;Paragraph F
Set up the XML template
In the XML template, you add HTML comments wherever you want to insert data from a column in the CSV file.
- The index of the first column is 0 (zero).
In the example file (template.xml) I’ve inserted one column in the H1 and another one in the P-tag:
<html> <body> <h1><!--[0]--></h1> <p><!--[1]--></p> </body> </html>
Convert the CSV data to XML files
Use the following syntax to create files based on the examples above.
CSVtoXMLconverter.exe "data.csv" "template.xml" "" "0.htm" ";"
The CSVtoXMLconverter takes 5 arguments to run
- The source CSV-data, (e.g. “c:\data\CSVdata.csv”)
- The XML-template, (e.g. “c:\data\XMLtemplate.xml”)
- The destination folder (e.g. “C:\data\stuff”). If left blank, the files are created in the same folder as the .exe file.
- The file name column (e.g. “0.htm” will create .htm files using the data in the first column as the file name)
- The type of separator (e.g. “,” or “;”, or “tab”). If left blank, “;” is used.
Your turn!
Did you find this useful? Let me know!
Found a few bugs? Let me know! 🙂
Good luck and have fun converting!
Tagged with: Automation, csv, excel, madcap flare, Technical Communication, Tool, Topics, VB
Posted in Automation, Excel, Uncategorized
Posted in Automation, Excel, Uncategorized
How to fold an origami crane
As a kid I wanted to learn how to do origami. It was pure magic to see someone take a square piece of paper and turn it into a bird, a frog, or even an elephant.
I decided to give it a try, and got a book from the library. Unfortunately, I couldn’t figure out the instructions, and I eventually gave up.
Twenty years later, I decided to give it one more try. This time I did not get a book. Instead, I found a video on YouTube. Twelve minutes later I had folded my first origami crane.
Origami crane.
The curious technical communicator in me started to think about different types of instructions for folding origami. I found four main types of instructions:
- Video. This is the digital version of someone showing you how to make the folds. That person has infinite patience because you can pause and “rewind” as much as you like. https://www.youtube.com/watch?v=Ux1ECrNDZl4
- Diagrams and text. Illustrations show crease pattern and folding directions. Text instructions provide additional information. http://www.origami-fun.com/support-files/origami-crane-print.pdf
- Pictures and text. This is like a stop-motion version of the video instructions, with written instructions instead of a speaker voice. http://www.wikihow.com/Fold-a-Paper-Crane
- Crease pattern diagrams. No frills. Experts only. Shows the necessary creases. You have to decide how to make them. https://techwritingengineer.files.wordpress.com/2014/08/2fb7a-cranebeforefinishing.gif
The book I had borrowed as a kid had only crease pattern diagrams… no wonder I couldn’t use them – I wasn’t an expert.
My first instinct when I want to learn a new skill is still to find a book to read. That might not always the most efficient way of learning, especially not craft skills.
My wife takes a different approach. She turns to YouTube first, where she’s figured out how to craft cool beaded jewelry – something I imagine is much hard to learn from a book.
“Procedural knowledge is difficult or impossible to write down and difficult to teach. It is best taught by demonstration and best learned through practice.” (The Design of Everyday Things, Don Norman)
Beaded jewelry.
I’d love to hear about your experience with learning new crafts – vote in the poll or leave a comment! 🙂
What kind of origami instructions would you prefer?
ps. If you want to learn origami, I recommend following Jo Nakashima on YouTube (https://www.youtube.com/user/jonakashima) ds.
Setting up a Kanban Board in MadCap Flare
If you’re a fan of using Kanban boards – the simplest way of implementing one in MadCap Flare is to use a TOC.
Setting up a Kanban TOC in Flare
- Create a new TOC and add items corresponding to your workflow (e.g. Backlog, In Writing, etc)
- Add topics to your backlog
- Work on one topic at a time, moving it along the TOC as you progress
Voilà – you have a simple but complete overview of your topics, and you keep topic administration to a minimum.
Stuff you can do with a Kanban TOC in Flare
Creating a review package
To create a review package, just right-click, for example, the “In review” node and select Send for review:
Creating a review package from a Kanban TOC.
When your reviewers open the review package, they’ll see your entire Kanban TOC, but will only be able to edit the topics in the node you chose:
Creating a review PDF
If you apply conditions to the Kanban TOC nodes, you can easily build a special review PDF if you set up the PDF target to include only the “In review” condition.
AUTOMATING reviews with batch builds and a little javascripting
To reduce the administration effort even further, you can set up a nightly webhelp batch build of e.g. the topics that are ready for review, and automatically send an e-mail to your reviewers asking for their feedback. To make it as easy as possible for them to supply comments, you can add a feedback button to your topics (for more info, see Adding a feedback button to your HTML5 output)
Generate a MadCap Flare TOC from Excel using VBA
When you are crafting a content specification table of contents, you might want to first “brainstorm” a TOC using Excel, and then simply export the structure to Flare once you’re done. You can write a short VBA function that does the trick. The animated GIF shows how it works and here’s a spreadsheet for you to play with. 🙂
For more info about content specifications, see Kai Weber’s excellent post about it.
To get the generated TOC to Flare, you need to create a text file, paste the result from the generateTOC_XML() function, and save the text file with the .fltoc file extension in the Projects > TOC folder in your Flare project.
Here’s the VBA code:
Have fun! 🙂
Customer specific documentation with MadCap Flare
Are you documenting a product that consists of a bunch of modules? Do customers buy customized products with a unique set of modules? Would you like to deliver customer-specific documentation using MadCap Flare? Keep reading.
The idea is to use an existing product module database to generate the condition tags, apply them to your content, generate the customer specific target files, and then set it all up to run as an automated batch job in windows 🙂
The process
- Build a condition set based on all the modules of the product(s).
- Apply the conditions to your content 🙂
- Use customer data to create customer specific target files (if possible, export from your ERP system to Excel).
- Use the target files to generate unique output depending on what modules/options a customer has bought.
Here’s an example XLS file for you to play with 🙂
Building the condition set
The idea is to replicate the Flare condition tag set XML file (.flcts) using Excel. The structure you want to replicate looks like this:
To set up a condition set “generator” in Excel, set up a spreadsheet that looks like this:
The Condition column combines the Product and Module names into a name for the condition.
The Flare XML column contains a formula that turns the condition into something we can put in the Flare condition tag set file (.flcts):
In addition to the conditions, we need to add the opening and closing XML tags: <CatapultConditionTagset> and </CatapultConditionTagset>:
Finally, we use formulas to combine all condition tags into a single cell that contains all the XML code we need for creating the Flare condition tag set file (.flcts). Have a look at the example XLS file to set how it’s set up. The final XML data looks like this, and is ready to save as a .flcts file in your Flare project:
When you’ve update the .flcts file in Flare, you now have a new set of conditions:
Applying conditions to your content
Granted your content structure supports it, you can now apply conditions to the module-specific text and images etc 🙂 Have fun!
Creating customized targets
The next step is to create customized Flare target files (.fltar). Again, we rely on Excel formulas to generate the XML data we need. The .fltar structure for a (PDF) target looks like this:
The Excel sheet looks like this (example XLS):
The resulting XML looks like this:
…and the resulting Flare target file looks like this:
In the Excel file, we’ve only customized the condition tags, but you could easily set it up to customize the document properties (title, subject, etc) as well.
Generating Flare output files based on the customized targets
When all your target files have been set up, you can set up a .BAT file to run on a schedule to generate your targets on a daily basis to ensure that all content is up-to-date.
You can use Excel to create the batch file, by creating a formula that combine the madbuild.exe command line tool with the path to your project and target (e.g. madbuild -project C:\PATH\FlareProject.flprj -target MyPDF)
Good luck, and have fun!
(I’m happy to help you create your your own setup – just ask :-))
How to add wiki-words to your HTML5 output in MadCap Flare
Would you like to link certain words or phrases to your internal wiki, or perhaps to Wikipedia? Would you like to build your output only once, but still be able differentiate between “internal” and “external” audiences? Keep reading.
The idea 🙂
The idea is to add a span-class to your style sheet, and then highlight the words or phrases you’d like to link to your wiki (or any external source). A javascript then creates hyperlinks based on the content within the <span class=’wiki’> tags. You then enable/disable the javascript by using a server-side include (SSI) statement (if your web-server supports it) that points to a file containing the javascript. If your web-server doesn’t support it, or if you want to try it out locally, you can just include the javascript in the master-page of your output. You could even use conditions to exclude the javascript from, e.g., external builds.
How to set it up using the master-page approach
- Add a span-class called span.Wiki to your style sheet.
- Choose any topic, and highlight a few words using the new span style.
- Open the master-page you’re using for the output, and add the following javascript to the top of the page:
window.onload = function (){
var wikiWord = document.getElementsByClassName(‘Wiki’);
for (var i = wikiWord.length;i–;){
var a = document.createElement(‘a’);
a.href = ‘https://en.wikipedia.org/wiki/’ + wikiWord[i].innerText;
wikiWord[i].appendChild(a).appendChild(a.previousSibling);
}
}; - Build your output – and voilà – the highlighted words or phrases are now linked to Wikipedia.
- Modify the script to fit your specific needs 🙂
Here’s what the output would look like:
Enjoy! 🙂
Posted in Javascript, MadCap Flare
Adding a feedback button to your Flare HTML5 output
Are you looking for instructions on how to add an e-mail feedback button to the toolbar of your MadCap Flare HTML5 output? And would you like a copy of the relevant URL included in the e-mails you get? Keep reading.
Open your Flare project, and follow these steps to add a feedback button to the toolbar:
- Go to the Project Explorer > Skins and open the HTML5 skin.
- Go to the Toolbar tab and add a new button called (e.g.) Feedback.
- Go to the Styles tab and find the sub-node called Toolbar Button > Feedback.
- In the Properties section, expand the Event node and add the following Javascript to the node: window.location=’mailto:your@emailhere?subject=<‘ + escape(window.location.href) + ‘>’;
- Expand the Background node and set Background Image to (e.g.) feedback.png (
). - Save the HTML5 skin and view your HTML5 output. Here’s an example of the output.
When you click the feedback button, your default e-mail client opens, and the URL of the current page is displayed in the subject field.
Have fun! 🙂
Keeping track of your Flare topics in Excel using pivot charts
If you are using file tags to keep track of your topics in Flare (e.g. 01 Created, … , 06 Published), and if you need a way to get a quick visual overview of all your files, keep reading.
Keeping track of file statuses
In the Flare File List, search for *.htm to display all your topic files. Export the list as a CSV file. Import the CSV file to Excel. Create a pivot table, and a pivot chart – showing the number of topics with each file status tag. The chart gives you quick visual overview of where in the production flow your topics are.
This also works great if you’re working in a collaborative environment with several writers producing content. A quick overview like this can help documentation managers, editors, and translators keep track of how much work is coming their way.
(If you have several blank items, like in the chart above, that might indicate that someone’s missed tagging a few topics.)
As a bonus, if you have a Flare project that in turns contains several sub-projects, in separate folders, you could filter the pivot table on the path of each folder to get an overview of the topic statuses in that specific folder, for that specific project.
Keeping track of the activity levels in your team
Another cool pivot chart is the one that shows you the number of files that have been modified each date, it could help you keep an eye on the activity in your team:
Cool, but… how?
- For help on exporting file data from MadCap Flare, see http://webhelp.madcapsoftware.com/flare9/Default.htm#Exporting/Exporting_File_Data_to_a_CSV_File.htm?Highlight=export.
- For help on importing CSV data to Excel, see http://office.microsoft.com/en-001/excel-help/import-or-export-text-txt-or-csv-files-HP010099725.aspx.
- For help on creating pivot charts in Excel, see http://office.microsoft.com/en-001/excel-help/create-a-pivotchart-HA102919712.aspx.
The benefits of working with small batches
I just read The Lean Startup by Eric Reis, and found that the Build – Measure – Learn cycle can easily be adopted in technical writing. The idea is to build (design, and write), then measure (SME reviews, editor comments), and learn from the data from the reviewers to build better topics in the next iteration. This works for small batches as well as large ones, but working in small batches gives you the added benefits of learning quicker, incrementally improving the product, and delivering useful content quicker. Working in small batches also lets you make course corrections earlier than working with large batches. It helps you avoid situations where you are delivering content that users don’t really want.
A story about stuffing envelopes
In the book (The Lean Startup) there’s an interesting story about a father and his two daughters stuffing envelopes. The daughters first address all the envelopes, then stamp them, and then fill them. The father processes one envelope at a time. The daughters are following the intuitive approach, but the father finishes first, because in the small batch approach, lead times are smaller – daddy doesn’t spend as much time sorting, stacking, and moving around the piles of envelopes. And because the father processes one envelope at a time, he starts delivering finished product almost straight away. The added benefit of processing one envelope at a time is that he quickly figures out if the letters don’t fit the envelopes, or if the envelopes are defective, and the seal doesn’t work.
How would this work in techwriting?
When writing, say, a new “manual” – one of the first things you do is to analyze the requirements – what are the end-user tasks I need to support, and what kind of topics (procedure, concept, reference) will do the job best. You might jot down a list of potential topic titles: “Installing the coffee maker”, “What is coffee?”, or “Making the perfect mocha latte”. Once you have that list in place, throw it into the review cycle – ask some of your SMEs if they think you’re aiming for the right target. Now – start writing, but not everything at once. Do small iterations with single topics. Once you have written “What is coffee?”, pass it on to your neighborhood SME who will then provide feedback on the accuracy and completeness of the topic. Incorporate the SMEs comments, and pass the topic on to the editor. Once you have received and incorporated the feedback on the topic, publish it! Even it’s supposed to be a part of a bigger product (e.g. a single topic in a user manual), just get it out there! Let your customers use the information, and maybe you’ll even get valuable feedback from them, letting you change course on the remaining topics if necessary.
The case for small batch writing
When you work with small batches, you get a finished product (a stand-alone topic) published quicker than if you’d wait for all topics to finish. In the process you get valuable feedback from your reviewers, editors, and possibly even users. This lets you make course adjustments already at the stage of creating the manual, rather than having to find out six months later that the manual is no good and you need to rewrite the whole thing. If you’re working with SMEs with a tight schedule, they might be able to fit in a single topic review while they’re waiting to get the tires changed on their car, but they would find the task of reviewing a complete manual too cumbersome to even think about. Working in smaller batches decreases the lead time, and you deliver an incremental product, which also improves incrementally because the feedback you get on each topic helps you improve the next one. The small batch approach is especially useful in more volatile environments where there is no anchored process for creating documentation – it’s easier to convince someone to review a single topic than a complete manual.
