Content Strategy: How Long is This Gonna Take?

It’s the very end of the month (a leap month, no less! I had an extra day!) and I’ve got a cou­ple of projects I want to post about, but they’re still in progress. So, instead of some per­son­al cre­ative or DIY stuff, I want­ed to post about some­thing more work-relat­ed for me. From the very begin­ning of my work as a tech­ni­cal writer, I described my approach to how I see my doc­u­men­ta­tion work being used as follows:

  1. Imme­di­ate: tool tip, pop-ups, hov­er info in your IDE. 
  2. Quick answer: F1 on what a dia­log field val­ues are or a function/method
  3. Long answer: search the docs and poke around until I find my answer
  4. Learn­ing: Inten­tion­al read­ing, in the order pre­sent­ed, if the documentation

Lev­els 0 & 1 both start in soft­ware or code and end there. This has the least and next-to-least inter­rup­tion to your work. The answer is imme­di­ate­ly when you need it or just a click & scroll away.

Lev­el 2 is often back and forth between docs and soft­ware. This inher­ent­ly can feel tedious. Often, this results in not even find­ing what you need (unless you were look­ing for frus­tra­tion). Unfor­tu­nate­ly, this is also where a lot of prod­uct help leaves you.

Lev­el 3 is sole­ly in the docs. You’re no longer per­form­ing your pri­ma­ry goal or job func­tion. This was not so com­mon for new employ­ees or employ­ees who just got a new tool in the work­place at one time. It feels like a rare lux­u­ry today, though. Too many work­places pri­or­i­tize keep­ing pro­duc­tive day-to-day over mak­ing their employ­ees pro­duc­tive in the longer term.

So, what’s the point? Lev­el 0 & 1 should be the goals, but they require sig­nif­i­cant more plan­ning and coor­di­na­tion with prod­uct devel­op­ers and UX design­ers. And, if we’re being hon­est, mak­ing Lev­el 2 work effec­tive­ly is going to require some of the same. And if you’re writ­ing man­u­als like any­one has the time for Lev­el 3, you’re shoot­ing your­self in the foot for all of the oth­er cases.

Needle in a Haystack

I just fin­ished what was one of the longest days of my career so-far at Bent­ley. And every­thing that was bad about today was entire­ly my own damn fault and could have been eas­i­ly avoid­ed if I’d just been a bit more careful.

In addi­tion to push­ing some pub­lish­ing updates to our doc­u­men­ta­tion CCMS last night, I also decid­ed to roll out my new Trou­bleshoot­ing DITA spe­cial­iza­tion. It’s based on the spe­cial­iza­tion that is expect­ed to ship with the DITA 1.3 spec­i­fi­ca­tion some­time next year, but uses our spe­cial­ized domains and works with DITA 1.2. That’s most­ly tech comm nerd talk for I decid­ed to give the writ­ers a new tem­plate geared toward writ­ing trou­bleshoot­ing tips.

Unfor­tu­nate­ly, even after thor­ough­ly test­ing it on our devel­op­ment serv­er, I man­aged to mess things up by added a com­ment to a cou­ple of DTD cat­a­log files after all of my test­ing but before mak­ing a back­up of the pro­duc­tion envi­ron­ment. That is, I did­n’t real­ly have a back­up of the func­tion­ing pro­duc­tion serv­er. Rather, I had a copy of some files I had just made a minor edit to, one of which includ­ed a crit­i­cal error. An error I end­ed up spend­ing all day today try­ing to locate and correct.

Even­tu­al­ly, I real­ized I had left a sin­gle “>” char­ac­ter in an XML com­ment copied over to a text cat­a­log file (the text cat­a­logs aren’t XML and have the angle brack­ets stripped out — some­thing I will now do with XSL instead of man­u­al­ly!). This one par­tic­u­lar cat­a­log file is used to locate the DTDs for our desk­top DITA edi­tor and no one was able to check out or cre­ate new con­tent in our CCMS as a result of that one errant char­ac­ter. It took me about ten hours to fig­ure this out (well, maybe nine hours of pan­ic attack and one hour of actu­al clear-head­ed work). Thus leav­ing half-a-dozen writ­ers with no good way to edit some of their files today as well as me feel­ing like a jerk for not being more cautious.

I just wrapped up my fix­es —both test­ed thor­ough­ly in their final form and put into place after back­ups of the work­ing pro­duc­tion envi­ron­ment were made. I’m going to check in with my col­leagues in India short­ly to ensure they can now edit and cre­ate con­tent once again.

Les­son learned; and I am humbled.

Make a Folder Manifest for XML Files

One task that has come up quite a lot as I’m work­ing with a lot of XML files (most­ly DITA con­tent) is I need a way to cre­ate a list of all the XML files with­in a fold­er. More than not, I want this list to be an XML file, too. There’s real­ly no fold­er- (or even file-) lev­el oper­a­tions in XSLT to do this. It’s sim­ply not what that lan­guage is used for. To do this, I had to cre­ate a sim­ple script. Using scrips like this is very easy to inte­grate into the DITA-OT (though not where I use this par­tic­u­lar script).

If you’re a web devel­op­er, there’s prob­a­bly many bet­ter ways to go about doing this than using a Win­dows Batch file. You prob­a­bly already know many of them. This isn’t intend­ed to be used in a web data sce­nario, but more for local XML data man­age­ment tasks.

The Windows Batch File

I per­son­al­ly real­ly like the Win­dows batch file com­mand lan­guage. It’s pret­ty sim­ple, even though it does lack a lot of nice fea­tures1. When you want to do fold­er or file oper­a­tions in Win­dows, I think it’s the eas­i­est thing to use even when you’re a real­ly poor pro­gram­ming like I am.

This batch file writes three pieces of infor­ma­tion to an exter­nal XML file:

  1. It writes a root node to an XML file. It also adds the fold­er path into an attribute of the root node, which can be use­ful for post-processing.
  2. For every XML file in the fold­er, it adds a child node after the root node’s open tag. These child nodes will con­tain a link to these XML files in the folder.
  3. It writes a close tag for the root note.

I refer to this new XML file as a man­i­fest, as it lists all fo the con­tents (well, XML files in this case, any­way) in the fold­er. Once an XML file is cre­at­ed with this infor­ma­tion, XSLT can then be used to use or change the infor­ma­tion in those files by run­ning against this man­i­fest file.

So, MakeManifest.bat looks like this:

SET output=manifest.xml
ECHO ^<manifest sourcepath="%~dp0"^> > %output%
FOR %%f in ("*.xml") DO (
    ECHO      ^<file href="%%~nf.xml"/^> >> %output%
ECHO ^</manifest^> >> %output%

Copy those lines into a plain text edi­tor and save it with the file exten­sion .bat and give it a try!. That’s all there is to it. If none of that makes any sense to you, I’ll refer you to SS64’s CMD ref­er­ence page.

It is worth not­ing that (and the sharp read­er might have fig­ured this out already) this list will include a refer­nce to itself, itself being anoth­er XML file in the fold­er. You could sim­ply rename the out­put file exten­sion to some­thing else (.txt, .man­i­fest, etc.), which is a good rea­son I put in a vari­able to make that easy to do. It does­n’t affect what’s in the file.

Post-Processing the Manifest File

In my case, these XML files tend to be DITA top­ics. What I’m real­ly after here is to cre­ate a DITA map. With a lit­tle XSLT file to process this man­i­fest —which can be run from the same Win­dows batch file— it’s easy to cre­ate a DTIA map for all of the DITA top­ics the script finds in the folder.

Now, to do this, I use Saxon9HE, which is the opens source ver­sion of Sax­on­i­ca’s (Michael Kay’s) XSLT proces­sor. It’s easy to use, very fast, sup­ports the lat­est ver­sions of every­thing, and free.

I’ll fol­low up this post with anoth­er soon about how to do just that. I want­ed to post this step first so as to not over­whelm some­one who is learn­ing (nor give me an excuse to put off post­ing anything).

  1. Most notably, to me, is reg­u­lar expres­sions. How­ev­er, the RxFind util­i­ty is a great way to add reg­u­lar expres­sion search and replace func­tion­al­i­ty to your Win­dows batch files and I use it a lot. []

Batch File Output in MadCap Flare

I have a cou­ple of prod­ucts which I doc­u­ment using Mad­Cap Flare to gen­er­ate about two dozen help files and anoth­er half-dozen PDFs. These out­puts are spread across mul­ti­ple Flare projects which I inher­it­ed. Pro­duc­ing a full set of out­put for a release can prove to be near­ly a full day’s worth of effort so I final­ly got around to cre­at­ing a sin­gle Win­dows batch file to take use of the com­mand line inter­face for Flare. Flare has had the com­mand line fea­ture for a few years now, but regret­tably, I just nev­er took the time to learn it. It’s actu­al­ly very sim­ple to imple­ment, even if you’re not that famil­iar with writ­ing batch files or the idea of the com­mand line scares you off a bit.

Tools Used

First, I should point out that to fur­ther stream­line my work, I’ve imple­ment­ed a cou­ple of oth­er tools besides just Flare. These are all free, open-source tools which I high­ly rec­om­mend you hav­ing in your tech-writer toolk­it1.

  • 7‑Zip — The best com­pres­sion util­i­ty out there. The com­mand line inter­face is easy to wrap a lot of files into a com­pressed archive (vari­ety of for­mats, includ­ing .zip).
  • NcFTP — A very easy-to-use FTP which has some com­mand line util­i­ties capa­ble of trans­fer in pas­sive mode (required for our FTP behind a firewall).
  • Notepad++ — A great text edi­tor which has syn­tax high­light­ing for batch files.

And of course Flare. How­ev­er, you could also eas­i­ly inte­grate much of the same work­flow into using the DITA Open Toolk­it as well as any oth­er help author­ing tool with a com­mand line interface.

Set Up

I pre­fer to use dates in my archive file names just to make things clear for the teams down­load­ing them what ‘ver­sion’ it is. Sure, we could just check time­stamps, but this just makes it more obvi­ous. I use the inter­na­tion­al data for­mat — YYYY-MM-DD — as the pre­fix for my titles and I want­ed this auto­mat­ed into my batch file. How­ev­er, as my region is US on my Win­dows machine, I need to just change the short date for­mat in the Con­trol Pan­el to this for­mat. That way, I can use the %date% envi­ron­ment vari­able to always input the cur­rent date when the archive is created.

Aside from that, installing the above tools is all that is required.

Creating the Batch File

Notepad++ can be used to cre­ate and edit the Batch file. Sim­ply cre­ate a new doc­u­ment and save it (some­where con­ve­nient) with the .bat file exten­sion. This also indi­cates the file type to Notepad++ so the syn­tax is high­light­ed appro­pri­ate­ly (sim­ply makes edit­ing easier).

I want to place my out­puts in a Zip archive for the con­ve­nience of label­ing them all with the cur­rent date and plac­ing onto a FTP serv­er for oth­er teams to down­load. So I set a vari­able to include the cur­rent date:

set ZipOut=C:\Documentation\Output\
echo %ZipOut%

(The sec­ond line just out­puts the same back to me so I can ver­i­fy the date string was as intended)

Next, I change the direc­to­ry to the Mad­Cap Flare installation:

cd\Program Files (x86)\MadCap Software\MadCap Flare V8\

Then I can use the com­mand line entry — madbuild — to ini­ti­ate builds of any num­ber of Flare projects and tar­gets (which are indi­vid­ual out­puts from a sin­gle-source Flare project).

madbuild -project "C:\Documentation\Product\ProductHelp_A\Product_A.flprj" -log true -target "Product_A HTML Help"
madbuild -project "C:\Documentation\Product\ProductHelp_B\Product_B.flprj" -log true -target "Product_B HTML Help"
madbuild -project "C:\Documentation\Product\ProductHelp_C\Product_C.flprj" -log true -target "Product_C HTML Help"

Next, I want these three com­piled HTML Help files to get placed into the ZIP file I named in my vari­able. This uses the com­mand line inter­face for 7‑Zip:

cd\Program Files\7-Zip
7z a -tzip %ZipOut% @C:\Documentation\Output\Product_file_list.txt

Where Product_file_list.txt is just a plain text file con­tain­ing the absolute file path and file name of each of the com­piled HTML Help files. It’s described in detail in the 7‑Zip help, but essen­tial­ly the entire file path for each file to be includ­ed is on a line in the text file. No spe­cial syn­tax or sep­a­ra­tors required.

Last­ly, I want to trans­fer the ZIP file over FTP to a con­ve­nient place for the rest of the team. The default Win­dows FTP pro­gram can­not run in pas­sive mode, which is required to nav­i­gate a fire­wall. How­ev­er, the Lin­ux FTP client NcFTP has been port­ed to Win­dows and has a com­mand line inter­face which is more flexible.

ncftpput -F -u username -p password /Product/ %ZipOut%

Running the Batch File

Just save the file in your text edi­tor. All that is need­ed to run it is to sim­ply dou­ble-click the .bat file in Win­dows Explor­er. The com­mand line win­dow will open, exe­cute each line in order, and close upon completion.

It would be easy to also use Win­dows to sched­ule run­ning the same thing night­ly or week­ly if you need to reg­u­lar­ly post updates of your work.

  1. There are OS X and Lin­ux equiv­a­lents to these, but not to Flare, which is why I’ve lim­it­ed this to Win­dows. []

Think Inside the Box

I saw this video today demo­ing a very inter­est­ing user man­u­al con­cept. Essen­tial­ly, the man­u­al wraps around a device with queues to manip­u­late the actu­al device, rather than some screen­shots or pho­tos. Basi­cal­ly the man­u­al is more of a phys­i­cal tem­plate (or jig, since I’m using tem­plate in the crafts­man sense).

Out of the box from Vit­a­mins on Vimeo.

How­ev­er, I can’t think of a worse device to apply this idea to than a touch­screen smartphone.

Let me explain: I’ve been using an Apple iPhone for about the past four years now1. As much as I ini­tial­ly opposed the idea, Apple was cor­rect in tak­ing things like the SIM card and phone bat­tery out of the hands of the user2. It’s a far supe­ri­or user expe­ri­ence to design those out of the expe­ri­ence all togeth­er, in my opin­ion. That being said, if you’re going to force your user into awk­ward set-up neces­si­ties, this is about as pain­less a way to do it as pos­si­ble. I can image some lay­ered gad­get pack­ag­ing where each sec­tion the user opens, they are pre­sent­ed with the next step in set­up or assem­bly (would work great for Ikea prod­ucts, too!).

Now, as for instruct­ing the user how to do any­thing on the phone: with a gen­er­ous sized touch screen, there’s sim­ply no rea­son why all of these instruc­tions can’t just present them­selves on the screen. My favorite apps on th the iPhone are those where the instruc­tions appear as modal dialogs point­ing to the most-used fea­tures. Add’l help can get includ­ed to, but the top two or three tools are called out as soon as the app launch­es, mak­ing any user almost instant­ly proficient.

So, as much as I like this con­cept, I’d much rather see all of this inside the box—er, phone—than in some bulky, phys­i­cal thing that isn’t going to be with you at all times.

In short: I think the man­u­al for a smart phone should sim­ply be one short sen­tence: Push the pow­er button.

Via Johne Cook, by way of Bill Swal­low & Ray Gal­lon

  1. Yes, this is the part where I start com­ing off as an Apple fan boy, but bear with me… it applies to any smart­phone or oth­er touch-screen device []
  2. Sure, you can still get to the SIM card on an iPhone, but com­pared to any oth­er phone, it holds vir­tu­al­ly no data beyond the user’s account cre­den­tials or phone num­ber. []

A DITA & DITA Open Toolkit Reading List

I was in the process of reor­ga­niz­ing my com­put­er sci­ence and tech­ni­cal writ­ing shelf today dur­ing lunch when I began to notice a pat­tern: I have quite a few books relat­ed to DITA and the under­ly­ing tech­nolo­gies of the DITA Open Toolk­it. Well, this isn’t by coin­ci­dence. It’s a big part of my job and some­thing I’m real­ly inter­est­ed in. But it occurred to me just how much time I’ve spent pour­ing through these texts of struc­tured author­ing and XML-based technology—all in hopes of grokking this for my job.

Some Light Reading on DITA

So, in no par­tic­u­lar order, here’s a list of some of my books on the subject:



A cou­ple of books on Ant & JavaScript that I haven’t even got­ten to yet:

And, some wider shots of my (sort of) orga­nized bookshelves:

Non-Fiction Bookshelves

Office Shelves

  1. I have the first edi­tion. I’d rec­om­mend get­ting the lat­er edi­tion. []

Regular Expressions versus XSLT

Last week I came across an epic rant with­in a forum thread1 about why using reg­u­lar expres­sions for pars­ing XML is a bad idea.

The <cen­ter> can­not hold it is too late. The force of regex and HTML togeth­er in the same con­cep­tu­al space will destroy your mind like so much watery putty.

At first, I was a lit­tle sur­prised. I love using reg­u­lar expres­sions to make bulk changes through­out an XHTML doc­u­ment or even across a project con­sist­ing of hun­dreds of files. But, after read­ing through the post sev­er­al times and thinkng about what I’ve been able to accom­plish with some (rel­a­tive­ly) sim­ple XSLT files and a XML pars­er, it occurred to me that it is absolute­ly correct.

You, see as great as reg­u­lar expres­sions are, they are not aware of the con­text. They have no idea if your match­ing a pat­tern with­in a C++ rou­tine or an XHTML file. They can only parse char­ac­ters and short strings as they are, with no under­stand­ing of their meaning.

EXsten­si­ble Stylesheet Lan­guage Trans­forms, on the oth­er hand, are sole­ly for the pur­pose of manip­u­lat­ing XML con­tent. By def­i­n­i­tion, they are aware of XML ele­ments and their attrib­ut­es. The entire pur­pose of them is high-lev­el mod­i­fi­ca­tions. In fact, after hav­ing used them now to suc­cess­ful­ly con­vert some XHTML to DITA XML, I have to say the pow­ers feel almost god-like.

RegEx still have their use with XML—particularly with bad­ly formed SGML/HTML one might have had dumped in their lap. But if the need is actu­al­ly manip­u­lat­ing XML ele­ments or attrib­ut­es with­in a file (or even across files), then it’s real­ly fool­ish to try to accom­plish some­thing with mul­ti­ple reg­u­lar expres­sions when a sin­gle XSL tem­plate will do (and often with­out the unin­tend­ed con­se­quences of a greedy RegEx).

  1. And when I say epic, I mean it goes from mak­ing a case as to why RegEx is sim­ply insuf­fi­cient­ly high-lev­el enough to deal with HTML pars­ing to open­ing the gates of the abyss and let­ting the deep ones in to your mind. []

Hacking the DITA-OT to Print Multiple Pages from a HTML Help File

Here’s one that took a lit­tle pok­ing around to fig­ure out. One of the many (nay, count­less) draw­backs of using HTML Help (.CHM files) is that print­ing from them is awful. Ide­al­ly, a user could print from the Help View­er to get a hard copy — or at least a .PDF copy — of the man­u­al. This would reduce the bur­den of try­ing to con­tin­ue to pro­duce .PDF deliv­er­ables for writ­ers like myself and keep all of the help in one place for the user, allow­ing them to print what they need1.

The Problem

So, as a writer, I’d like to be able to style dif­fer­ent­ly for the screen and for print. There are a whole host of rea­sons why (dif­fer­ent read­abil­i­ty issues, scale issues, etc.) but often as not because web browsers just don’t print every­thing they ren­der for the screen. Back­ground col­ors or images, for instance, don’t get sent to the print­er. This can quick­ly go from a style issue to a read­abil­i­ty issue.

While CSS gives the writer a fair bit of con­trol over the dis­play medi­um, good ‘ole HTML Help is right there to block you. It all works just fine when you print only the cur­rent top­ic. How­ev­er, HTML Help offers this won­der­ful lit­tle fea­ture which allows you to print the cur­rent top­ic and all child top­ics (for exam­ple, the Chap­ter head­ing and all con­tents of that chap­ter). Sounds great, right? Except for how it is imple­ment­ed breaks all links/references between files.

Print Topic dialog in HTML Help Viewer

The Print Top­ic dia­log: The cause of all this trouble.

That’s right. Hyper­links? Bro­ken. JavaScript? Not only bro­ken, but will now present big, scary error warn­ings to your user2! And CSS? Com­plete­ly busted.

You see, when you select this option in HTML Help, Win­dows copies all of your files (con­ve­nient­ly renam­ing them, thus break­ing links between your top­ics) into some tem­po­rary fold­er and them con­cate­nates them into one long HTML file, which it then prints just as it would have the sin­gle top­ic file (minus all of the CSS, script­ing, and oth­er things I, as a the writer, spent weeks on).

The Solution

For­tu­nate­ly, we can use one of Win­dows’ oth­er odd­i­ties to com­bat this one. That is, the very strange behav­ior of .CHM files in the file sys­tem. For some insane­ly odd rea­son which I can­not fath­om, Win­dows sim­ply does­n’t care about the fold­er where a .CHM file was placed. Upon open­ing it, it sends it to some oth­er place where direc­to­ries and fold­ers don’t exist and you sim­ply only need to call for the name of the file and it will locate it no mat­ter where it is on your machine.3

So, where we would have put a rel­a­tive file path with­in the .CHM file’s inter­nal fold­ers, we will use the MS-ITS syn­tax call to bring it forth! There is no place safe for these tem­po­rary print files that Win­dows cre­ates due to it’s own absurd behavior. 

Now, obvi­ous­ly, this all applies to any HTML Help file, not just one cre­at­ed using the DITA Open Toolk­it. How­ev­er, I’ll show you some of the extra know-how it takes to pull this off from with­in you’re author­ing tools if you’re using DITA. Some oth­er help author­ing tools have options to cor­rect for this4.

The Hack

  1. Cre­ate a new style sheet for use with print dis­play or sim­ply use an @media print { } block to add print-relates styles to an exist­ing style sheet. You can ref­er­ence the same style sheet mul­ti­ple times in the same HTML file with (appar­ent­ly, in HTML Help View­er, at least) no ill effects.
  2. Locate the XSL file respon­si­ble for adding the <head> con­tents into your HTML files: dita2htmlImpl.xsl

    For exam­ple, for XMet­aL, this file is locat­ed in C:\Users\<>\AppData\Roaming\SoftQuad\XMetaL Shared\DITA_OT\xsl\xslhtml\, where <> is your Win­dows user name. On old­er ver­sion of Win­dows, AppData is Application Data and this is usu­al­ly a hid­den sys­tem folder.

  3. Near the end of this long XSL file, you’ll find a num­ber of <xsl:template>s, one of which is used to gen­er­ate links to CSS files.

    Hint: Just do a search for the string “text/css”.

  4. Go to the end of this Tem­plate (the </xsl:template> line) and add the fol­low­ing link:

    <link rel="stylesheet" type="text/css" href="MS-ITS:<your.filename>.chm://<file.path>/<>.css" media="print" />

    Where: <your.filename>.chm is the name of the HTML Help file you’re gen­er­at­ing. Note that you’ll need to update this file for any dif­fer­ent out­put file­names you gen­er­ate, unless you want Win­dows open­ing up some ran­dom .CHM file every time the user clicks Print.

    <file.path>/<>.css is the rel­a­tive file path and stylesheet name inside the HTML Help file. If you real­ly just aren’t sure, grap a copy of 7Zip and use it to peek inside your .CHM (it can read them just like a .ZIP file; awe­some thing to have in your toolkit).

I’m fair­ly cer­tain this con­cept can be applied to the issue of <scripts>, as well (though I haven’t got­ten it to work thus far). How­ev­er, it will nev­er fix the issue of hyper­links between top­ics as this sys­tem of con­cate­nat­ing files into a tem­po­rary file irrev­o­ca­bly breaks those links. You can’t do a one time read this file back in the source .CHM for that issue.

A huge cred­it goes to Yuko Ishi­da who sent the key to this over to I should also point out that this hack was test­ed in HTML Help Work­shop v 4.74.8702, Win­dows 7 64-bit, XMet­aL Author v5.5, and DITA-OT v1.2.

  1. In engi­neer­ing, it is occa­sion­al­ly nec­es­sary to print off some of the tech­ni­cal ref­er­ence or method­ol­o­gy sec­tions of design soft­ware doc­u­men­ta­tion for clients. []
  2. God only knows we’ll get calls about virus­es on this one… []
  3. Tru­ly, this has the poten­tial to wreak hav­oc should you have two or more .CHM files of the same name on your local dri­ve. How­ev­er, for the most part, it is com­plete­ly invis­i­ble. I can assure you, I have oodles of copies of var­i­ous .CHM files with the same name and I only recent­ly learned about this Win­dows weird­ness. []
  4. Mad­Cap Flare, for instance, has an option to cor­rect the appear­ance of mul­ti-page print­ing for .CHM files which I’m fair­ly cer­tain does the same thing as I describe here. []

Designing User-Focused Context Sensitive Help

This pre­sen­ta­tion by Matthew Elli­son [Goog docs] giv­en at last year’s Aus­tralasian Online Doc­u­men­ta­tion and Con­tent Con­fer­ence (AODC 2009) has some excel­lent points on how to craft online help for con­text sen­si­tive calls. This is some­thing Bent­ley uses (a lot) and I’m try­ing to catch up on. There are real­ly a lot of excel­lent points in these slides. I believe that even if you aren’t employ­ing con­text-sen­si­tive help, struc­tur­ing your help as though you were is just as like­ly to get your users to their answers faster.

Also, the slide in this pho­to (from the same con­fer­ence) made me laugh out loud (lit­er­al­ly, not in a LOL sort of way).

Clarity Trumps Brevity

Dan Sil­ver­man does­n’t like his Avaya desk­top phone1 very much. He explains how its cryp­tic but­tons don’t real­ly pro­vide enough infor­ma­tion to make sense of their func­tion. He also includes this gem on what hap­pens when indus­tri­al design fails (which is almost always, to some extent):

Yes, in the case of elec­tron­ic devices, the design should intu­itive­ly con­vey how it works with­out the need for a man­u­al. But if the design is bad, a man­u­al is the next best thing.

Writ­ing the man­u­al or the help should be inte­gral to the process of design and not left until the end (or worse, after the prod­uct ships). Good man­u­als and help can indeed be the next best thing to an inspired design and make prod­ucts far more usable.

1see how I invent­ed a new phrase to describe an old thing based on the way we do things now?