Tag: <span>Recently Read</span>

Another week (and a bit) has passed. Time is tight for me at the moment, and I’m not posting here as often as I’d like so, for now, here’s a quick roundup of everything that’s zipped past my inbox in the past week:

Resources on presentation design

… advocates an assertion-evidence design, which serves presentations that have the purpose of informing and persuading audiences about technical content

Needless to say, with my first ever conference presentation looming, I’m fairly focussed on both topic relevant stuff and anything that will help make my presentation better.

An XML CMS is simple as 1-2-3

Creating an XML-based Content Management System to single-source technical publications is as simple as 1 – 2 – 3. Rather than focusing on any single tool or solution (and thereby forcing users to change to match the tool), this article describes one possible three-step process for using XML to single source your content deliverables.

A rather simplistic view of things, but if you are a bit flummoxed by the raft of information available in this area, and you aren’t really sure where to start, have a quick look at this. Short, simple and easy as A-B-C.

Make your writing east to scan

… the acid test is looking at your information as your reader/user would see it, and asking yourself “can I find what’s important without reading the whole page”?

You can format your text in a variety of ways, but it pays to take a step back and view the format of your content from the point of view of your readers.

Getting to the web-first mentality
Interesting to read that other professions are struggling to embrace the internet. Ultimately I think it’s getting to the point where we just need to take the plunge.

Start putting the web content management system into the workflow at the front end. This could be as simple as using Google Docs as a word processor instead of the bloatware that we know as MS Word.

Collaborate or fail
Titled “Building a Collaborative Team Environment” the opening couple of paragraphs kept me reading:

Technical communicators work hard to meet deadlines and value the standards inherent in the profession. At the same time, they value their personal creativity and the responsibility for developing a complete publication on their own. They tend to enjoy doing everything from writing, editing and page layout, tographics, technical content, and more.

Working as part of a team to create a single set of deliverables, handing over responsibilities to fellow team members, and trusting the work produced by others does not come naturally.

It’s an excellent article, looking at a variety of ways in which we, as technical communicators, can adapt how we work. It will no doubt prompt some posts here as I digest it further.

And on that, somewhat culinary note, I’ll thank you once again for stopping by.


Comments closed

12 Lessons for Those Afraid of CSS and Standards

“It took me two years to break out of the comfortable prison of layout tables, and another two years before I could use CSS to produce layouts that were originally intended for tables.”

“The buzz about Web 2.0, CSS, and myriad other subjects of the bleeding edge can become a dull roar to those left ill-equipped for industry changes because of work habits adopted in good faith years before. It is my hope that the experience I’ve shared will help some folks to find a way back to the top of the heap—which is where the web needs you.”

But don’t be afraid, Ben Henick offers some lessons that will help get you through. It’s based on real-life experience and mirrors my position. CSS and standards are good, yes they can be strict taskmasters but remember that 100% compliance isn’t always required, sometimes 98% is enough. As Ben points out in Lesson No. 9: “In the real world, stylesheet hacks will get your project across the finish line”

Design Engineering

“The common expression “Engineers build bridges” is actually a misnomer. Engineers build mathematical models of bridges and draw little pictures of bridges on paper or inside computers. Ironworkers are the people who really build bridges. This inexact, industrial age metonym has led to much confusion in the post-industrial age, where it’s all too easy to confuse software designers with software welders because they both use the same tools and raw materials for their very different work.”

Not sure I agree with all of this but I always tend to learn more from a differing opinion.

What do you seek — Documents or Knowledge?

“Document management can only point you towards documents, like a traditional search engine. In contrast, when you’ve got information on a wiki you can search for information, link to it, reference it, update it, secure it, blog about it and share it.”

I’ve been pondering the possible questions that might crop up when I give my presentation on using Wikis in the workplace, and this is a great answer. So much of using a Wiki is about breaking the document-centric working practises that slow us all down. Don’t they?

The Spiral of Wiki Adoption

“Although reliance on email and familiarity of other tools may illustrate a reluctance to ‘unlearn’ habitual less effective work practices, there needs to be a balance between directive wiki usage and support for different communication styles as people become accustomed to using wikis and the different capabilities they can provide.”

During other research I found that just getting people to start using a Wiki was the hardest part. Once they started, they soon started using it in ways not previously considered. In other words, Just Do It.

And finally, two quick links. One I’ve known about for a while but recently cropped again on TechWR, and the other is just for kicks. Although I do often wonder if people do Laugh Out Loud as often as all that.

A List Apart: Style Guide


As ever, I’d love to hear your thoughts on any of these. Particularly the Design Engineering article which I must admit I partly agree with but I do dislike the “them and us” tone.


Comments closed

As a wise man once said, time flies like a banana. I may be paraphrasing (badly at that, sorry Groucho) so let’s skip on quickly. Brevity is the name of the game today for whilst I’m delighted that the company is allowing the development team to swan off for an afternoon of beer and ten-pin bowling, I am still losing several hours from my working week. With that in mind..

ISTC Conference 2007 writeup
File this one under “Ask and ye shall receive”. I’m a member of the ISTC but couldn’t make it to the conference, so I pinged their mailing list to ask if anyone who had attended would possibly write up their thoughts.

Many thanks to Mike Unwalla for taking the time to write up summaries and thoughts on the presentations he attended:

  • Keynote address by Scott Abel
  • Certification for Technical Authors
  • Translation-oriented authoring—a prerequisite for efficient authoring
  • Managing the lifecycle of your technical communication
  • Leveraging DITA in a multilingual environment
  • Writing justifications and comparative analyses
  • Developing a communication-across-the-curriculum culture
  • Staying agile
  • Reasons to be cheerful—part 1
  • CMS: how to avoid a content mess system
  • Around the World in 80ms

Of key interest to me was the thoughts on working in an Agile development environment, with the suggestion of “Decoupling the publication of documentation from the delivery of the software” being something we are discussing at present. More on that later.

Scott Abel on Web 2.0
A shared set of slides from a presentation that aims to help us better understand how the semantic web (that’s the Web 2.0 bit) is impacting on technical communications, and how we can leverage some of the tools and ideas to our benefit.

I’ve touched on this myself a little, although I’m pretty sure the biggest impact is, and will remain, Google. This area is still (constantly) evolving so it’s worth keeping an eye on things.

Dependency Calculator

“In determining the risks involved in completing a publications project on time and on budget, some years ago my organization developed a simple assessment tool that we call a Dependencies Calculator.”

And oldie but a goodie. I developed something very similar at a previous company and after a few iterations it proved very valuable.

Requires Java.

Information R/evolution
Interesting little video that explores the continuing evolution of how we treat information. Simple and yet powerful and thought-provoking.

Sun Labs lightswitch

“I gave a talk at Sun Labs where I encountered a special light switch in one of their conference rooms. At first I thought it was some kind of silly “engineer” joke. But the light switch functions as stated for real.”

An excellent example of over documenting something rather than changing the design

Who am I?

“The biography is probably one of the most basic elements in a portfolio (what kind of website or blog doesn’t have an “about” page?) but can be one of the difficult. To this day, I still haven’t written one I’m 100% happy with. But hopefully with some different perspectives, it can be easier.”

I struggle with this kind of thing too, some good hints which should help improve things a little.

Writing for the Web
The website of the book that I’m now waiting on being delivered (gosh, what an ugly sentence).

PDF exploit in the wild
Sorry to end on a bum note, but something to note for those of you who, like me, distribute docs in PDF format. Don’t worry, it’s not as bad as things are made out (but what ever is?).


Comments closed

Another week, another quick set of links. I really should start using one of these new fangled “social bookmarking” sites for this, shouldn’t I. Problem is I already have a del.icio.us account for personal use, and I like being able to add some thoughts about the links but it limits that slightly.

In saying that, it does mean I give each link proper consideration, rather than just bookmarking them in passing. With that in mind, I thought I’d change the format of this post a little and offer a little more thought on each. Hopefully the links remain interesting and useful to others.

In a (short) post entitled Identical vs derivative reuse Ann Rockley suggests that

“one thing is certain, that companies can reuse more content then they think”

If you are currently investigating reuse opportunities within your company then you should find this interesting. Understanding the potential is a key part to forming your single sourcing business case, and if nothing else it offers some handy reminders of places to look.

Anne Zelenka wonders why companies are moving away from cubicles to open plan spaces to aid communication, and proffers some suggestions in her post titled Mold the virtual space, not the office space

“Lots of web workers are traditional employees and go to an office every day. But they can still take advantage of the web to reach out inside and outside their company.”

In my personal experience, open plan offices are a boon to the technical author in many ways. Physically locating a technical author with the development team that they are working with ensures that they catch all those snippets of information that typically disappear into the ether.

However, the downside is the constant distractions and background noise. As such I tend to spend a few days a month working at home, setting work aside for those days as I know I can tackle larger chunks of work with little to no distraction or interruption.

The first of two links to the ever thought provoking Ann Gentle. Her article The “Quick Web” for Technical Documentation, which discusses using wikis for technical documentation. is available as a downloadable PDF. The article was recently published in the STC magazine Intercom and others sage advice (as ever).

Keeping on the wiki theme, I came across a summary report from an MBA student that covers Managing Wikis in Business:

“indicates that wikis have provided platforms for collaborative and emergent behaviour, enabling people to work/communicate more efficiently and effectively, learn from past experience and share knowledge/ideas in organisational contexts that are not averse to collaboration”

I’ve not read the full report yet, but looks very interesting.

Are you involved with the UI design of your application? Joshua Porter makes the case that you should be as interfaces need editors:

Editing is mostly about clarity and making the interface concise. It’s a lot of copy-writing, and only a little rounding corners.

With a task view of how an application is used, there is an easy ‘in’ to this area for most technical writers.

Sticking with UI design, if you are interested in this area have a look at these articles from Apple Insider. Whilst they are focussed on new elements of the “soon to be released” Apple OS, they start back in the days of early GUI. Fascinating stuff, or maybe just a nice bit of nostalgia. The articles cover the new Dock, Spaces, and Finder.

Finally a doozy of a post from Ann Gentle. It’s the type of thing that makes my head spin and sort of, maybe, ties in with my own thoughts on structured authoring within an Agile development environment. Single sourcing documentation, following a structure such as DITA, matches the fast pace of Agile development, to improve collaboration and make the sharing of discrete chunks of information more open a Wiki makes sense. So, in my mind there is a match, or at the very least a correlation between structured authoring (DITA) and Wikis. However Ann, in discussion with Chris Almond and Don Day, comes to get:

“a sense that there are two camps in technical documentation. There’s the “quick web” folks who connect easily and author easily, and then there’s the “structured quality” camp that requires more thoughtful testing and time spent on task analysis and information architecture. Also, the types of information that these authors are trying to capture are opposed in some senses.”

It’s a fascinating post and has certainly got “ideas popping and synapses firing” in my brain. Are structured authoring and wiki opposing forces? is a question which is going to keep me occupied for a while.

That’s all for now. Next week I’m going to try and NOT feature a post (or two) from Ann Gentle but we do seem to share a lot of similar ideas. Don’t worry, I’ll “spread the love” as they say.

Right I’ve got a presentation on Using Wikis for Collaboration to finish. Pass the caffeine please.


Comments closed

First up, apologies for my absence over the past week or so. We decided to sneak a few days in Spain as a last minute holiday (before my wife starts her new job next week) and as it was all a bit rushed I didn’t have time to post anything here. Until then, here are some of the things that have pinged my interest in the past couple of weeks. Some may be a little old as I’m still catching up but… as ever, they may, or may not be of interest:

There’ll be a lot more on Wikis in the coming couple of weeks, and I’d love to hear YOUR thoughts and feedback. But more on that, later.


I’ve had my head stuck in various planning documents, so a shorter list than usual but, hopefully, thought provoking none the less.

  • Documentation = dollars ~ “Software development without documentation is self-centric. Documentation is a signal that the developer actually cares about her downstream users. For projects that actually want downstream users, write good documentation. It won’t cannibalize buyers: it will create them.”
  • TechComm Pros Wiki – could grow into a very useful resource, and as it’s a Wiki you can help.
  • TICAD 2007 – OK, this one is a bit cheeky as I’m going to be speaking at it. More on that later, but the programme looks interesting and has some excellent speakers (I’ve shared dinner with Bernard Aschwanden who is smart, engaging and… tells a dirty joke like you wouldn’t believe).

That aside, the issue of blogging came up on TechWR yesterday, with some people stating that they didn’t read blogs as they were just one persons opinion… but to me that is entirely the point. Admittedly weeding out the opinionated from the passionate, and the intelligent from the insulting can be tricky, but you soon gain a good radar for such things.

And I guess I should ask, which am I?


Comments closed

Another week, another list of articles that I’ve found interesting or useful. As usual they are spread across various areas, from technical writing, to information architecture and web design. Hope you find them interesting:

  • Scenarios and Minimalism – if you only visit one of the links today, make it this one. To summarise hugely, it’s all about user and task analysis, and matching the outcomes of your analysis to your writing methodology.
  • User Centred design – a paper investigating the different theories and methodologies evolving in this area. A bit dry at times.
  • MIKE2.0 Wiki – I’ve been looking into MIKE, purely out of curiosity, and this wiki is the best place to start.
  • 7 Lies of Information Architecture – an excellent starting point with links to respected resources. Should help debunk some myths, e.g. Lie 2. “There is a magic number (plus or minus two).”
  • What is Success? – “Success means… engaging with a social world: a world of clients and employers, but also of readers, users and other designers. It is those things that make us rich.”

Other than that, I’ve updated the TechComms RSS list (over on the right there), and if you do download it and find it useful, please let me know. I’m maintaining it for myself but happy to take requests if there are any sites you think I’ve missed.


Comments closed

I’m not sure if this is lazy blogging, or a useful feature but here, again, are a few of the articles and blog posts that caught my eye over the past week.

  • Audrey Carr on Design Briefs ~ “After a series of small projects involving undefined requirements, fuzzy objectives, and an aparent lack of truly insightful customer insights, I’ve spent a good chunk of this week thinking about the strategist’s favourite tool for communicating with creative and account teams: the brief.”
  • Inline Linking is bad for usability – whilst it’s aimed at those people concerned with optimising their content for search engines, the examples are interesting from a writing point of view as well, swap out “usability” for “readability” perhaps.
  • Linking DITA Topics using Relationship Tables – If you are investigating DITA have a skim through this, yet another way to increase the power of DITA
  • A mile wide and 30 seconds deep ~ Mike Hughes on how to focus your help content, “…focus the Help on what it does well, that is, provide a wide variety of 30-second informational solutions to get most users back on track and in task”
  • Help Authoring Tool matrix – has been running for a few years now and is a bang up-to-date, excellent resource.
  • The Rockley Blog – Ann Rockley and Steve Manning, of the Rockley Group and that book (Managing Enterprise Content: A Unified Content Strategy), have a blog. I had dinner with Steve, and others, after the X-Pubs conference this year and this is definitely a blog to watch.

OK, that’ll do for now.

Hopefully, by this time next week, I’ll have finished the new design for this site and will start posting a little more regularly. There are a few things I would like to explore, and hopefully I can get some feedback from you, dearest reader. Make sure you subscribe to the RSS feed to catch the next post.