Sunday 14 October 2012

Creating an information map from multiple word documents

When I'm asked to plan information for a new customer I usually start with a content audit. The quickest and easiest way to understand a suite of MS Word documents (and give yourself a place to keep notes) is by creating a spreadsheet of the documents and tables of contents (TOC).

For a while I've been creating these spreadsheets by laboriously copying each TOC from each Word document (in the latest set, that's 35 documents). This time though, I asked the STC single-sourcing special interest group (sig) for help to automate the process and they gave me a web link that suggests using RD fields to collate all the TOCs into one.

I've written down my process here. It's a bit rough and ready but hopefully it helps. Obviously you'll need to adapt it to your situation but it gives some tips in terms of creating CSV files and using regular expressions for search and replace. If it helps you then please leave a brief comment :)  Thanks.


  1. Follow the instructions here to build an RD TOC (thanks Virginia).
  2. In MS Word, switch off page numbering and hyperlinks in the TOC so that it is headings only.
  3. Copy and paste the TOC into Notepad++
    My TOCs have heading numbering which I can use to create commas for a comma separated value file (CSV). Spreadsheet programs can open CSV files as spreadsheets.
  4. To prevent genuine commas breaking the structure, in Notepad++, search and replace commas "," with a unique string like c0mmr4.
  5. Press Ctrl+H for search and replace and select Use regular expressions.
  6. To extend the heading numbering style with an end period, replace tabs with a period:
       Replace "
    \t" with "." (no inverted commas).
  7. To create the correct number of cells indent, replace numbers followed by period with a comma:
       Replace "
    [0-9]+\." with ","
  8. Save the file.
  9. Grab the file and folder name; right-click the Notepad++ tab and select Copy complete path.
  10. In MS Excel, File > Open and paste in the file path and name.
  11. Search and replace "c0mm4" with ",".
  12. Click OK.
That's it. You should have an outlined TOC for your suite of documents. Now you just need to read them :)

Monday 9 April 2012

DITA without the DTD

A couple of months ago, I led a training course in DITA XML. The first two days were stock slides, concerned with the DTDs, conref and conkeyref mechanism, then, the third day, the one I wrote, was entirely about the DITA philosophy, the semantic nature of the DTDs, progressive disclosure and writing great short descriptions (shortdescs).

Rupert the bear providing progressive disclosure
Rupert the bear providing progressive disclosure

More recently, I've been asked to use Adobe Technical Communications Suite (TCS 3.5) to create content. As for previous assignments, the current documentation is unstructured, does not reuse content, and the help and PDFs are not  single-sourced. That is, the help systems are entirely separate from the PDF and content is copied between the two. I'm assuming this is reasonably common. The team members are all professional writers of a certain quality but, outside of word choice and a few style guide rules, the content varies quite considerably in approach and overall style.

For my part, and probably from my long term exposure to DITA XML, I have adopted many of the writing philosophies that it provides and I work them into my normal output. For instance, progressive disclosure. If I am writing an introduction in a chapter, I don't write, "This chapter tells you about..." and list the subjects, I write a summary that includes high level facts from the subject matter and let the reader make the assumption that this is the subject of the chapter.

Then it hit me, why not formally introduce the writing rules of progressive disclosure and short descriptions into the current writing guide. Why not aim for a DITA-like layout in tasks? Why not, as a team, plan the information set with Task, Concept and Reference topics as if we were using DITA. The double-benefit of this approach is that it results in more consistent documentation, and, should the decision be made in the future to move to DITA XML, we have topics that are ready for the transition.

Wednesday 4 April 2012

Comparing Snagit with Microsoft Clip Organiser and Snipping Tool

I'll be honest. I've never purchased a license for TechSmith Snagit. In earlier versions of Windows, I've always used ALT+PrtScn and Windows Paint. However, the other authors here use Snagit and expect me to use it too, and, I'm a big fan of TechSmith Corporation. I use Camtasia, Jing and Morae when I can and they are excellent tools. For me, these tools set the bar in usability.

So, I like Snagit because it is shiney and easy to use. But, can I just use Windows Clip Organizer and Snipping Tool to replace the ever-so-useful Snagit? While the snipping tool allows you to save as PNG, it doesn't integrate at all with the Clip Organizer except through copy and paste.

The first hurdle with Microsoft Clip Organizer is that it doesn't offer a Save As option. In fact, it doesn't offer Save at all. However, with a little investigation, I discovered that it automatically stores images in a folder called Microsoft Clip Organizer in My Pictures.


Windows Explorer showing the Microsoft Clip Organizer folder

But, these are uncompressed bitmap files which are unsuitable for most uses. Ideally for my needs, they need to be PNG files. If I right-click on them, guess which application presents a "convert" option - Snagit of course.

The next hurdle is that the Clipping Tool only offers free-form, rectangular, window, or full screen clips – only a slight improvement on ALT+PrtScn. Snagit offers a whole bunch of different capture options including special features like scrolling through web pages and list boxes. Without Snagit, I'm stuck with connecting these together in Paint.net.

Finally, Snagit stores all the images you have previously captured in a database that displays across the bottom of the Snagit Editor. That's exactly what Microsoft Clip Organizer does too. It's main feature in fact. You can assign keywords/tags and a captions but, and it is a big BUT, you can't decide the filename or format and so you can't recognize them outside clip editor.

So, I'll stop there. I think Microsoft Clip Organizer and Snipping Tool fail when compared with Snagit in the following important ways:
  • From Snipping Tool, you don't get an automatic database of previous clips
  • From Snipping Tool, the editing and highlighting is unconstrained and scruffy
  • The Snipping Tool is not integrated with Clip Organizer
  • From Clip Organizer, you can't save files as a different type or rename them
  • From Clip Organizer, you can't edit files or launch their default editor
A little more integration between the two tools would be a very good thing but, for now, I think that Snagit is an investment worth making.


Monday 12 March 2012

Report from 5th March event, Self-service support starts in the UI

This was a joint event between the ISTC, Northern User Experience, and the Manchester Metropolitan University usability lab.
Rachel Potts of 3di Usability described findings and techniques she has used to improve the user experience of software. Techniques that apply equally whether you approach software from a documentation or user experience (UX) design point of view. Improvements in each of the five areas she looked at were backed up by solid evidence either from a usability lab or through technical support statistics. Of the five areas, the two that stood out to me were the focus on clear error messages and the idea that you should break the rules. After all, when are customers most likely to call Tech support? When they receive an error. A clear message can go a long way to helping them serve themselves. As for breaking the rules, users have become jaded over the years and have lost trust in standard help mechanisms, so the idea here is, if you are providing content that is truely useful, you now need to make it stand out in some way, perhaps by glowing or appearing in the UI instead of the help.
All in all, the evening was a resounding success for all parties. 3di who provided the refreshments, the ISTC who were exposed to several potential new members, MMU usability lab who met some of the movers and shakers from UX in the north of England, and myself who will be taking this experience back to my new challenge at AppSense and putting it into practice.
Thank you Rachel

Thursday 9 February 2012

US and UK Spoken English

Writing technical information in US English is one thing. However, over the past few days, Baxter, a hula-hooping expert from North Carolina, USA, has been staying with my family.

This is Baxter:



This led me to recite my two favourite observations about the difference between UK and US spoken language:

Communication can be one way at times
Because films and media generally flow from the US to the UK but not back the other way, North Americans generally do not understand our idioms although we generally understand theirs. This can lead to blank stares during normal conversations or snorts and gurgles as they try to get their head around our anglicisms.

The richest field for alternative words is the automobile, sorry, car.
Starting from the front we need to translate:
Bumper  > Fender
Headlamps > Headlights
Bonnet > Hood
Windscreen > Windshield
Gear stick > Stick shift
Boot > Trunk
Rear lights > Tail lights
Exhaust pipe > Tail pipe

If you have any more for my collection then do let me know.

I'll finish with one final anecdote:
A few years ago I was getting out of the car with my Texan friend who shrieked with delight when I exclaimed, "Oh no, I've trodden on a boiled sweet" as I got out. She just didn't know what I meant. It turns out that, actually, I'd "stepped in a candy".




Wednesday 8 February 2012

Second guessing what the user needs

I often say that my job is to be an advocate for the user within an organization. I shouldn't just document the tasks that the user wants to achieve, I should also push back to the development team to explain when the software presents barriers to achieving tasks.

However, how do we know what real users are trying to achieve with the software? We can make a best guess based on previous experience but, new features are new features and don't necessarily have a precedent. What then?

I've heard it said several times recently that we should be writing the bulk of the user documentation after the product is released and that we should base the tasks we document on needs identified from technical support calls.

Indeed, several large companies are already doing this.


Skype online help


This has parallels with the release early and release often of Agile and Scrum software development where features bubble to the top of a list. I get the feeling that post-release documentation will be the hot topic of 2012.

Tuesday 7 February 2012

Nobody's talking about it

The circles I move in so far aren't considering the implication of the movement of English language technical communications to lower-cost India. However, in the UK there has been a dip in contract rates and writing rates have remained more or less static for perhaps 10 years.


The list of panelists from the tcworld India 2012 conference makes interesting reading:
  1. Ken Chu, Senior Director of Information Development, Server Technologies, Oracle Corporation, USA
  2. Suneeta Aggarwal, Director of Technical Publications at TIBCO Software Inc, USA
  3. Sonali Natarajan, Director of Documentation, Cisco Corporation, USA
So Oracle, TIBCO and Cisco now write their content in India do they?

I read a while back that by working with India from the UK, both economies would grow. If that is true, what we need to do, rather than burying our heads in the sand, is embrace that idea and start working together.

For many businesses in the UK, success can only come by working in the team with the developers and engineer subject matter experts (SME). Writing requires understanding and expertise but, which bits of the process could you share with a lower cost colleague? How does your organization aid you in forming those relationships? It's time to start thinking about these issues.