The blog has moved to www.techwritingengineer.com
The blog has moved to www.techwritingengineer.com
Here’s a tool I developed that transforms CSV-data into XML-data based on a template.
You can use it to, for example:
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!
To convert files, you need
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
In the XML template, you add HTML comments wherever you want to insert data from a column in the CSV file.
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>
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
Did you find this useful? Let me know!
Found a few bugs? Let me know! 🙂
Good luck and have fun converting!
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.
The curious technical communicator in me started to think about different types of instructions for folding origami. I found four main types of instructions:
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! 🙂
ps. If you want to learn origami, I recommend following Jo Nakashima on YouTube (https://www.youtube.com/user/jonakashima) ds.
If you’re a fan of using Kanban boards – the simplest way of implementing one in MadCap Flare is to use a TOC.
Voilà – you have a simple but complete overview of your topics, and you keep topic administration to a minimum.
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:
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.
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)
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! 🙂
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 🙂
Here’s an example XLS file for you to play with 🙂
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:
Granted your content structure supports it, you can now apply conditions to the module-specific text and images etc 🙂 Have fun!
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.
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 :-))
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 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.
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); } }; |
Here’s what the output would look like:
Enjoy! 🙂
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:
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! 🙂
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.
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.
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:
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.
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.
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.
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.