Tomorrow we get to spend the afternoon in the pub after gorging ourselves on turkey and stuffing. Yes, it’s the Development Christmas Lunch. This year it’s handily placed right at the end of a release cycle (although that does mean some poor souls may be dragged back into the office), so we can celebrate the release AND the birth of a baby a long, long time ago (or whatever you believe).

That also means that next week I’ll have a little more free time to think about the future, and get some plans in place. I’ve already got a fair list, some of which will feature here.

However, for the time being, here are a few things that caught my eye the past week (or so).

Writing Tips for Non-Writers Who Don’t Want to Work at Writing
As THE core skill of my job, some of this is a little hard to take but sometimes we can be a little too obsessed with grammar, don’t you think?

Grammar matters, but not as much as anal grammar Nazis think it does … Frankly, I think if most non-writers can manage to get agreement between their verb and their subject, I’m willing to spot them the whole “who/whom” conundrum.

Wiki Patterns: The Book
I love it when this happens, a blog I’ve read for ages (devoured some would say) gets published in book format. Needless to say my copy is already ordered.

Human behavior is pattern-based, and wikis are designed to support the
patterns of activity that occur when groups work together. Therefore, there’s no right or wrong way to use a wiki, so it’s impossible to write a recipe for successful wiki use that will work in all cases.

Instead, documenting the behaviors seen on different wikis and classifying those that help the wiki effort as patterns, and those that hinder the wiki as anti-patterns, is a more useful
way to offer guidance to other wiki users.

Use Structured FrameMaker and WebWorks ePublisher?
Sticking with Wikis, here is an excellent article from the WebWorks Wiki: Implementing Help-Specific Features with a FrameMaker EDD.
I probably learned more about using Structured FrameMaker with WebWorks reading that article than I have in the past year of actually using both products in anger (although that’s mainly because the set up here works so I’ve not had to tinker).

This project contains a complete workflow for producing printed and on-line documentation with ePublisher Pro. At the heart of the system is a structured FrameMaker template with an underlying EDD. The minimalist EDD contains a scant nine content elements and yet automatically assigns more than 120 paragraph styles that implement help specific-behaviors in the corresponding ePublisher Pro template.

Building Enterprise 2.0 on Culture 1.0
Sounds a bit odd I know but if you are interested in how to build an collaborative environment in your organisation then you must have a look.

To encourage an organisational shift along the enterprise collaboration maturity model, Enterprise 2.0 leaders should focus on capturing the flow of information. Over time, the flow builds not only a stock of searchable knowledge but also a reputation as the source of fresh ideas and trusted up-to-date content.

And finally, a little house-keeping. I had promised to update the OPML file of TechComms RSS feeds but I’ve not had a free minute. It’s top of the list now though, so expect to see an update early next week.

With the TICAD conference last week, a couple of days in my sick bed, and the imminent product release I’m working towards, I’ve not had a lot of time to post here. However, the RSS feeds keep trickling in, so here are a few items that caught my eye over the past couple of weeks.

What Beautiful HTML Code Looks Like
I’m a terrible coder. Which is just as well because I’m not a developer but as I do dabble in HTML and CSS quite frequently (hey, and PHP too), then this is a good reminder for me to develop my own best practises.

Code is Tabbed into Sections: If each section of code is tabbed in once, the structure of the code is much more understandable. Code that is all left-justified is horrific to read and understand.

Includes a neat infographic, downloadable as PDF, which is now pinned beside my desk.

Procedures: The Sacred Cow Blocking the Road
An update on a (yipes) 10 year old article. I don’t think I read it when it was first published but I have read it. Well worth another visit though.

“It takes a surprisingly short amount of time for a user to feel unstuck. When I was a usability consultant, I used to advise clients to put the critical information in the first three words of a sentence.”

IA Deliverables
From Content Surveys, to wireframes, Personas and Use Cases, a brief overview of each is followed by a sample template. Not only a useful resource but a good overview of the typical process an Information Architect will undertake, a lot of which can be adapted to more traditional product documentation.

Collaboration is not a dirty word
Collaboration on content (not documents, even if that is where the content ends up) was a key part of my presentation. It’s good to see the switch from document-centric to info-centric taking place.

I love things being this easy. I love getting (almost) zero emails with attachments. I love not having a hard drive full of Word documents.

DITA Troubleshooting specialization

The Troubleshooting specialization creates a new topic type that is well-suited for problem-solution information.

7 Ways to keep the post-conference buzz
Not long back from a conference myself, I have already done a few of these things (item 3 in particular) but some good ideas here.

Wikis for Documentation?
Steve Manning isn’t sure about using Wikis for Documentation but does think they could be a big hit in another, related area:

Most writers have to guess about their users. Few writers get the opportunity to speak directly with users. Few get any sort of feedback at all. They are left to do their best. How useful would it be to be able to post your document on a Wiki and have users be able to comment topic-by-topic? To see the questions they ask?

I totally agree. All I need to do is figure out how this works within a single source environment, and tackle a few issues around governance and change management and it could be an excellent working model.

And finally…
I’ll be updating the TechComms RSS feeds download soon, so if you think you should be on the list (or even if you aren’t sure whether you are or not) then let me know. It includes all kinds of stuff which is loosely related to Technical Communications, and I’m always on the lookout for more sources of inspiration. Leave a comment if you think of anything.

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.

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

LOL?

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.

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?).

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.

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:

• Content is a Science, not an Art ~ “There is a ‘right’ way to write content. Sure, it may not be the ‘perfect’ way, it may not be the way Shakespeare or Joyce would have written it, but it’ll do. It’ll get results and deliver value. A production line can be set up where this content can be mass produced, tested, and measured.”
• Adobe announce new Technical Communication Suite which includes closer linking between FrameMaker and RoboHelp (closer than the standalone products that is). And, thankfully for me, Anne has an excellent roundup of the best coverage.
• Dive into Web 2.0 ~ a comprehensive guide to what it is, and what you can find ‘in it’.
• Ishikawa Diagram ~ also known as a fishbone chart. I’d come across these before but never knew that much about them. I do now.
• And so, to Wiki - I’ve to hand in my presentation for TICAD in a couple of weeks, so I’ve been doing some additional research about Wiki technologies and usage:
  • I started by asking readers on my other blog for their thoughts and was treated to some excellent insights and ideas.
  • This excellent and informative interview is a must if you are considering using a Wiki as part of, or a means towards, your documentation.
  • I’ve been asking myself this question recently: Is Using Customer-Accessible Wikis for End-User Documentation Gaining Momentum?. Whilst the conclusion isn’t particularly revealing, the article is full of examples and useful information.
  • Wikipedia is not the real world ~ covers a point I’ll be making in my presentation (although I derived my view from Chris Anderson’s book, The Long Tail)
  • I also stumbled across the Wiki Patterns website which is full of useful ideas and prompts.

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.