Tag: <span>Recently Read</span>

Almost halfway through the year and I’m still finding new technical communications blogs. If you have recently started blogging about this wonderous profession of ours do let me know. On with the last findings.

Web 2.0 and Truth
Sarah O’Keefe presented at the recent X-Pubs conference on Web 2.0 and Truth. It’s an interesting read, including three quick points which speak volumes as to where the future of our profession may lie.

1. Document publishing needs to accelerate.
2. Online documents should allow for comments and discussion.
3. The documentation needs to be explicit about product limitations and workarounds.

14 Widespread Myths about Technical Writing
An intriguing look at our profession, Tom challenges some of the myths about technical writing and comes up with some great responses. The comments are well worth a look as well. This kind of post always seems to attract attention as, by it’s nature, our profession can be very hard to nail down accurately as there as just too many variables. Tom’s approach is one of the best I’ve seen.

Using Personas to Create User Documentation
The worlds of usability, user interface design, and product documentation often overlap and in this article Steve Calde outlines how technical writers can use Personas (often used during product design) to help write better documentation. It’s basically an advanced take on “known your audience”.

Understanding what is important to your audience can help you create task-oriented scenarios that may include using several functions in a particular sequence.

Closed-Loop Publishing Brings the Wisdom of Crowds to Dynamic Documents
I’m always a little wary of these kind of whitepaper/bluesky articles, particularly because they are often written by some with a vested interest in making the topic sound interesting (they want to sell you something). However if you step past the marketing-ese language used there is some interesting points here, another pointer that Web 2.0 is going to (should already be!) shaking up our industry.

Traditionally, publishing processes have been more like a monologue than a discourse, with no formal means to facilitate this two-way exchange. This is finally beginning to change, and it has profound implications for the publishing model we know today.
The rise of dynamic documents offers an interesting parallel for this transformation. What if documents were the basis for — not just information dissemination — but a fully interactive conversation between the content publisher and the content consumer?

That’s all for now. Hope you find these posts as interesting as I did.


Comments closed

I’m utterly failing in my attempt to make this a weekly feature on this site. Maybe I should cut it down a little, thoughts and comments are appreciated.

Writing an Interface Style Guide
Some handy tips for what to include in any user interface guidelines document:

Interface style guides are extremely useful to define best practices for design and development. However, keeping that information updated and functional is imperative. A glossary, an index, references, acknowledgments, etc., are among some of the supplementary details you can add to make the style guide as helpful as possible.

A Climate of Fear among Technical Communicators?
Prompted by a panel in the recent STC Summit, Ben Minson outlines some basic tenets of employment which, whilst we all know them, bear being repeated:

I think protection lies in being inventive. If management and your peers see that you go beyond the bare minimum and the mediocre because you’re interested in what you’re doing, they’ll see value. If you invent in order to solve problems and to benefit your team and the organization, they’ll see value.

Interestingly, this aspect of professional life raises some issues, some of which were encountered by Anne Gentle at the STC 2008 Summit.

STC2008 – Wrap up STC Summit trip report
Anne heard a couple of similar issues during the summit (as well as a lot of other great stuff), but she noted that:

proving that [an] idea needs to be implemented in the first place means understanding how to convince management of the value.

It seems to be something we all struggle with, providing ROI to back up our reasoning behind choices of tool and technology. Which brings me neatly to the next post…

What is the Best Metric to Measure the Success of Your Reuse of DITA Topics?
Of course you’ll have to have provided enough evidence to at least get a pilot project or proof of concept off the ground, but if you have, how do you get the most from the data you are capturing. Bill Hackos suggests you should measure the percentage of repository words that are reused in context:

The ratio of the repository content to the produced content metric works at the content level rather than at the topic level. This metric is proportional to actual costs because translation is charged by the word, and maintenance costs are proportional to the volume of content rather than to the number of topics.

I’m not a huge fan of such quantitative measures but sometimes needs must. The article mentions some other possible metrics, and if you are considering a single source rollout give it a look as it will spark some thoughts I’m sure.

Finally a couple of quick links that do exactly what they say on the tin:


Comments closed

A quick note this week: If you know of any blogs out there that focus on hardware documentation writing I’d love to hear about them. I’m keen to see if there are other topics being covered out there as I’m aware that my scope is defined by my current interests. Right, let’s press on.

Can online help show “read wear?”
Anne Gentle ponders on how best to show the online help topics which have the most traffic, and comes up with some interesting ideas:

“You could … show the most searched-for terms when the user searches. Concepts may be more easily connected when you understand what others were searching for.”

To my mind anything that helps people find what they are looking for is a good thing, and these more subtle, dynamic, pathways are a tangible advantage to delivering content online.

Do We Really Need Structured Document Formats? (Is Real Reuse Possible?)
Eric Armstrong investigates the many and varied aspects of structured authoring, and offers a balanced view of the pros and cons from his own point of view:

“I know from personal experience that it is possible to be “seduced by the capacity for reuse”, to the point that you over-engineer your docs like crazy, and take forever to deliver something “perfect” that would have much better received had it been much more imperfect, and much more rapidly produced!”

Can better technical documentation give your business a competitive advantage?

…technical documents – the user guides and help systems used regularly by customers – at the centre of the corporation-customer relationship, and calls such documents “value generators” as they help build trust and confidence.

Striving for Success in DITA Conversion – A Quick Reference
From Noz Urbina, some sage advice that I’m filing away under “Obvious but worth being reminded of”:

A lot of people see ‘project scoping’ as overhead that delays ‘production’, but it’s a classic example of ‘measure twice, cut once’.

A bit short and sweet this week, such is the price for a four day week though.


Comments closed

Another grab bag of, hopefully, interesting posts, it’s a varied bunch this week which fits with my current mindset which is grabbing at a large variety of different topics and trying to make sense of them all (and I think it’s finally beginning to come together). Enough of that, on with the links!

Do you write FAQs? How about NAQs?
As Kevin Kelly points out, we’ve all read FAQs which aren’t, instead they are NAQs – Never Asked Questions, “Easily answered questions that no one has ever asked.” He then goes on to make an excellent point, namely that:

…if you don’t answer the FAQs, the internet tubes will. That’s what forums are. Customers, both potential and present, bring their real questions to find real answers. Here people who don’t work for the company will supply answers. Often these answers are good, but often the organization could supply a better answer, if it were really running a FAQ. Why not make it easy for everyone to find the best answer — from the organization’s point of view?

A Quarky new approach?
I mentioned Quark’s new Dynamic Publishing product when it was announced, and after initially being a little excited (“dynamic!” “publishing!”) I became a little confused by what it was actually going to offer.
Sarah at the Palimpset blog took an in-depth look and found that it was really just a form of single source, and suggests that:

if the “dynamic publishing” bit in the name is a preview of coming attractions rather than an accurate label for what they have now, then perhaps there’s hope. But I’m glad I’m not the one trying to pull this off because from out here, it looks like an extreme long shot.

The post is an excellent investigation of what drove Quark down this route.

Information Design Patterns
WARNING: Site requires Flash and is heavy on bandwidth.
If you ever have to create an infographic (a graph or other type of formal diagram) then have a look at this website for some inspiration and ideas for the future, as well as some in-depth analysis of the form factors presented.

Top 8 mistakes in usability
Given that we have recently revisited the idea of using personas and have spent some time trying to guess what they should be point 2 hit home. I know, I know, nothing replaces research based on REAL users.

Let’s pretend our user’s name is Jane. Let’s pretend she is 38 years old, drives a purple Prius, reads mystery novels, loves bulldogs, and likes to go sailing. Let’s pretend she comes to our website and likes feature A but not feature B. Therefore, we should develop more things like feature A. See? We’re very customer-centered.

This is the fun of creating a persona, which allows teams to make decisions based on fictional people, rather than doing the hard work of listening to real customers.

We actually decided to focus more on user roles first, before broaching the subject of Personas, and I’ll be doing my damnedst to make sure we don’t run into these mistakes.

Trends, tools, technologies in online documentation
Sarah Maddox wrote up some great notes from the recent Australasian Online Documentation and Content Conference, including these from the session by Joe Welinske which was based on the results of the WritersUA Skills and Technologies Survey. Some interesting observations on Vista, trends in our profession and some things that we should all have on our radar, including:

Structured authoring — affects a growing number of technical writers. Joe sees this as the most important concept for us to learn about. It affects our roles and production process. The author works in a form-based environment, putting the content into pre-determined pigeonholes. Presentation is separate and automated.

I quite like the fact that this isn’t stated as single source which has other connotations. Perhaps more of us are closer to structured authoring than we think? I mean, we all use templates and predefined formats, don’t we?

That’s it for now, time to get ready for the bank holiday weekend here!


Conference season is underway, with DocTrain and AODC recently finishing. As such there is a lot of great and interesting blog posts out there, some are catchup style so if, like me, you didn’t attend you can still get some nuggets of information from them. But the type I prefer are the ones which collate the various ideas and pull them together.

So, with that in mind, if you only read one of the posts linked below, make it the first one.

DocTrain Conference thoughts
Tom chats to Noz Urbina from Mekon and starts to pull together some of the varied threads I’ve covered here into a vision of the future which, in my opinion, makes sense. It’s great to see this kind of thing being discussed and it’s the step beyond where I’d gotten with my thinking. Well worth a read.

Some thoughts on writing better error messages
Real-world tales of woe shed some light.

This lack of coordination between error reporting and error origin often leads to incorrect human reasoning about root causes. One simple help to sysadmins (and other users) would be to report errors in context.

Separating content, structure, format and behaviour

One from a session of AODC which helps properly define how and why we should be separating out the various components of information production.

What we’re aiming for:
* Maintainability — you can change one of the above four components without breaking the others.
* Re-usability — you can re-use the same bit of JavaScript, for example, in other documents.
* Separation of skill sets — different people can work on the component they know best and enjoy most.
* Simplified updating of content — content is likely to be the component you update most often.

Designing for the Social Web: The Usage Lifecycle
Pertinent to anyone working with an application that has any form of social web (web 2.0, community interaction, pick a term) features, or for those of us trying to build an online community around their product

The lifecycle is particularly relevant to web-based software because the product is inextricable from the service. The product is the service. If a person has a question about what your software does, for example, you can literally build that answer into the software itself.

Wiki on a Stick
And finally, a downloadable, zero install, personal Wiki. May be useful if you want an example of how Wikis work. Extra handy for maintaining your own To Do lists or as a way to centralise your notes (or both).

That’s all for now.


Comments closed

I took a few days holiday last week (if you get the chance, go visit Budapest, it’s lovely) so here’s a little bit of catchup from the RSS feeds I monitor. You can download the list over on the right there.

How Corporate RSS Supports Collaboration and Innovation
Dennis McDonald pulls together some good arguments around introducing Web 2.0 ideas to your company, noting that a lot of business cases rely on raw numbers and that, in the case of social networking tools, there is:

… a disadvantage of taking a “beancounter” approach to implementing social media within an organization. While you might be able to quantify the time, effort, and technology associated with impacted processes, you can’t necessarily predict when and where the benefits (such as innovations or new ides) will occur.

Bye Bye GoLive!
Adobe finally realise what most web developers already knew, GoLive can’t compete with DreamWeaver (also now owned by Adobe). However, it’s not all bad news if you are a GoLive user:

the company will continue to support GoLive users with online tutorials and migration assistance created by usage experts. The company has also collaborated with online training service Lynda.com to provide tutorials for GoLive users.

And one more thing
The Hoefler & Frere-Jones blog continues to provide some fascinating information for typographists (?) and writers alike. This time they take a look at the many forms of the ampersand.

As for the word “ampersand,” folk etymologies abound. The likeliest account, offered by the OED, is explained by early alphabet primers in which the symbol was listed after X, Y, Z as “&: per se, and.” Meaning “&: in itself, ‘and’”, and inevitably pronounced as “and per se and”, it’s a quick corruption to “ampersand,” and the rest is history.

The Dawning of the Age of Content – and why Content Convergence Matters to You
For anyone watching the way information is now created, collated and distributed on the world wide web, this article will ring true. We ARE all watching what is going on, aren’t we?

We’re all content producers. And we’re all about to live through interesting times with the dawning of The Age of Content. Industry is discovering content as a commodity, as inventory with value, and the rules are changing fast.

The new rules are not just for high-profit content like movies and music. What was once seen as the lowliest form of commercial content within an enterprise – technical manuals, support documentation, and other business content – is starting to take its place alongside other valued corporate assets.

The 10, 20, 30 Powerpoint rule
An oldie but a goodie, it’s often quoted but it’s worth re-reading (especially as I’ve just pulled together a presentation that has.. eh… 23 slides.. ). It’s not always applicable of course but well worth keeping in mind.

It’s quite simple: a PowerPoint presentation should have ten slides, last no more than twenty minutes, and contain no font smaller than thirty points.

Summer of Doc, anyone?
Janet has a good idea for getting student technical writers (and hey why limit it?) a little bit of experience.

Now in its fourth year, Google Summer of Code supports students in writing code for participating open-source projects, which provide mentors to help guide the students’ work. Thanks to Google’s sponsorship, the students receive a stipend (making this a summer job), and mentors receive a nominal compensation for their time.

If you substitute code/documentation, developers/tech writers, Computer Science/Technical Communication, I think it’s fairly obvious that the same benefits could apply to Tech Comm students writing documentation for open source projects.

And finally a nice quote from the late great Douglas Adams:

” I love deadlines. I like the whooshing sound they make as they fly by. “


Comments closed

Blimey, another week has flown past and, as ever a few things have caught my eye.

9 ways to gather user feedback
It’s often a struggle to get true user feedback on your documentation, Craig Haiss offers some suggestions to improve things in this area. Whilst I’ve tried some of these, and had heard of them all, it’s worth a look to jog the memory:

You can write the most detailed instructions in the world, but if they aren’t the instructions users actually want, you’re wasting your time. That said, how do you go about gathering feedback to flesh out your documentation?

Tech Comm Job to Job Title: Something Lost in Transit?
Ben Minson is musing on job titles and, as well as raising a giggle, ends up stuck. Job titles, as a way to convey what you do for a living, are important.

… the dictionary says one who documents is a “documentalist”—however, I’m reluctant to adopt a job title that includes the word “mental.” So this is where you get “documentation specialist.” The same goes for “usability specialist.”

It seems a little funny that, being writers at heart and therefore professional manipulators of language, some of the terms we pick for our field don’t easily translate into job titles.

I’m currently experimenting with the title “Technical Information Manager” which is a little OTT but seems to fit my current role, thankfully my company, like myself, isn’t hung up on formal job titles (they prefer that you, you know, get on with whatever needs done). So, what’s your job title?

Typography humour

Glossary of DITA terms
Bob Doyle is wondering if there should be a central, user-maintained, glossary of DITA terminology:

many DITA-related terms are not defined … They are simply assumed.
And some is insider jargon, like reltable for Relationship Table.
And there is no convenient alphabetical listing.
You can search for terms on the DITA Infocenter, but then you have to already know the term.

This got me thinking. If you have been toying with setting up a documentation Wiki, then this may be an excellent place to start. It might also throw up some interesting usage of terminology. Definitely something I’m going to have a stab at (well, I’ll add it to the list of things to try).

RoboHelp vs Flare
Interesting round up of posts and comments on this topic. If you use, or are planning to use, either product, give it a look.

And I’m done. Another week in the wonderful world of Technical Communications has gone, I wonder what next week will bring?


Text Preferences Survey
What is the ideal text size to use on the web? What about line height and column (line) length? Most of the information in this area is based on print (at best) or anecdotal (at worst). A design agency in Brighton, Message, has decided to try and find out by carrying out a survey:

“Our goal is to publish a report that provides hard facts about what constitutes ‘readable’ text on the web … We see this report being of value not just to our clients and their customers but to web users at large.”

It only takes a few minutes to complete so go and take the survey.

Why software applications need product blogs and why they don’t get them
As well as having a very long title, Tom also hits on some points well worth considering if you are at all web savvy (and I’m presuming that, as you are reading this blog, you are). Most of his ideas are spot on but would require a lot of business process change, but I think they are worth picking up on:

I can think of six major ways product blogs can benefit users and project teams. Product blogs can …
– Provide a venue for product announcements
– Allow users to submit product bugs
– Allow users to submit feature requests
– Provide a roadmap preview for the product
– Enable a point of connection between users and project teams
– Provide a way to teach advanced tips to users

He also mentions something that I too have pondered, namely including RSS feeds in online help and somehow merging the two in a more dynamic way than before. Probably not much point in purusing that now but who knows what may happen in the future.

How to work better
A short list of simple, but powerful, advice which is applicable to everyone. Go on, there is at least one thing on that list that you could do better (or if you are like me, 3 or 4).

Subversion for writers
Entirely focussed on Mac OSX users, this has reminded me that we use Subversion at work and that I should really write up our process. Regardless of platform, the basic benefits of using a version control system can be realised with little cost.

What does it do? It manages multiple versions of a project in development. You check your project out of the repository, make changes and you commit those changes back to the repository. At any time you can view older versions of the whole project or of individual files, and revert to them, if the work done since was in error. You can make branches, which allows you to develop your work in two (or more) ways in parallel, and you can tag your project to say, at this point I met a certain milestone (eg: first draft, second draft, version sent to publisher X, version sent to publisher Y, published version, etc.)


Comments closed