This post has been bubbling for the past year or so, ever since I started this blog. It’s a bit of a ramble but if I don’t publish it now I’ll just keep adding to it and it’s long enough as it is!

I question everything. It’s part of the way my mind works, and is something I’ve embraced and believe it makes me better at my job as a technical communicator. That attitude has also helped me realise that there is a common thread that can be found across several different areas of our industry, which I (and others) are slowly pulling together. Convergence is the word that springs to mind, and as businesses clamber onto the social networking bandwagon, now is an excellent time to grab the reigns and take control.

Let’s step back a little.

Late last year, on two separate mailing lists, I followed discussions about what the myriad of people who share my profession have as job titles. I prompted one discussion on the ISTC mailing list, and chipped in some thoughts on the TechWR mailing list before dropping out later on when the noise ratio, as ever, got too high.

I wonder how much useful information I miss when I do that? Ahhh something else to ponder. But not today.

Anyway, discussions around how we as a profession should be referring to ourselves, envitably leads to discussions and thoughts about what we do, where our skills lie, and the benefits we can bring to an organisation. Something I’ve toyed with before, but which is wrapped up in many layers of ifs, buts and other such caveats.

Following on from that, I read an article by Virginia Lynch in the CIDM newsletter (and if you aren’t subscribed to their newsletter, you should be) entitled Information Developers - The New Role of Technical Writers in a Flat World which encapsulates a lot of my current thinking on how to take my current team forward, making sure we are matching company strategy whilst allowing the team members to retain a focus on maintaining and developing their core skills. The article title rather neatly alludes to Thomas Friedman’s book The World Is Flat: The Globalized World in the Twenty-first Century which is certainly worth a read.

Virginia mentions that JoAnn Hackos recently referred to these core skills as “Basic Hygiene”, citing the fact that, regardless of how the collation and production, distribution and usage of information may change, as we explore the burgeoning arena of new tools available to us under the banner of “social web applications” our core skills remain. Typically they tend to drop off as we are pushed to create more, faster, with a rise in quantity favoured over a maintenance of quality.

style, grammar, punctuation, spelling, and even clarity seem to have been sacrificed for quantity —JoAnn points out that knowledge of basic writing skills is still critical to our success as writers. Basic Hygiene also comprises an understanding and appreciation of editing, the information development life cycle, fundamental web and computer skills, and of course attention to detail.

However it is important to note the nod towards quantity being a business leader, and those of us tasked with managing a team need to consider how we achieve that business aim, without impacting our integrity as Technical Writ… umm… Information Developers?

So, how do we produce more whilst maintaining quality?

Wait! What’s that coming over the hill? Ahhh yes, the shining white knight of single source, armour gleaming, his trusty DITA (or DocBook) in hand, ready to do battle against the ills of productivity measurements and over-zealous QA departments. What else were you expecting? Ohh more resource? No, not these days when everyone is a “content creator”, not these days when we should be embracing and encouraging our audience to help plug the gaps in our information dykes (I really must stop mixing my metaphors).

Topic-based writing certainly seems to tick the required boxes and every business case and ROI I’ve read (and I’ve written a couple myself) points us towards the promises found over the horizon and the “he’ll be here real soon, honest” arrival of the aforementioned white knight. The trouble is that, whilst it is easy to agree with the theory, I’m not all that sure the white knight is all he seems. Certainly as we climb the hill towards him, auditing our content, deciding on chunking levels, agreeing metadata requirements, we begin to see that that armour seems a little thin and dented in areas, and I’m not entirely sure the knight is filling that armour as much as he should. Aren’t they supposed to be big strapping warriors? He looks a little weedy to me…

Topic driven content written with a minimalist slant, deferring here to the instructions of Strunk and White* rather than Roy Carroll, are where we seem to be (need to be?) heading and that’s fine and good from where I’m sitting.

* A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all his sentences short, or that he avoid detail and treat his subject only in outline, but that every word tell.

On the flip side, there is a definite growth in awareness around the use of Web 2.0 technologies and systems, building online communities, integrating Wikis, blogs, RSS feeds into the information flow either as part of end user deliverables or as methods for encouraging information creation by everyone involved with the product, internal or external.

A large part of our job concerns the collation and filtering of information so as far as I’m concerned anything we can do to make the creation of source information easier has to be welcomed. Extending these mechanisms beyond internal usage means it should be easier to provide information to the people who really need it, with the added bonus of a greater level of trust in that information. Don’t believe me? Which type of information do you put most weight on, the information passed to you by a trusted colleague who you know uses the product heavily, or the product documentation? (and bear in mind that we technical writers pre-disposed to favour the work of our peers). That in itself is another issue which may be alleviated by embracing social content creation, pulling on the goodwill generated by openly inviting contribution and collaboration, whilst giving technical writers a chance to show their worth in full public view.

So where is all this heading? I’m not sure if anyone is too sure but there do seem to be some trends appearing. The use of Wikis to host documentation, the creation of community websites with few restrictions, and more. There are plenty of tools, and with a little work you can get them talking to each other. Technology is not the limiting factor anymore, attitudes are now the only things stopping us trying these wonderous new things. It’s a big step for some companies, and some people, to free their information, to pass their hard earned knowledge about willy-nilly without a clue as to how it will be used.

Once you’ve gotten past the limitations, the real effort, once you have your community or collaboration up and running, is the surrounding processes. Do you want to pump content into the website regularly? (yes). Do you want to allow anyone and everyone to contribute to that same store of information? (yes). Do you want to allow others to quietly correct your mistakes? (yes). Do you want to give the people who need it, access to information about your product, regardless where it originates, trusting them to use their judgement? (yes).

The final pieces of the jigsaw are the finer details of implementation. Presuming we want to reuse information as often as possible where do you store information and how do you allow access to it? Who should be involved in verifying new information? Where/how is the level of trust established?

Pulling together the threads of this emerging role is tricky, with so much overlap into multiple areas and so much to consider there is a danger of not seeing the wood for the trees. This post is an attempt to step back and make a little more sense of what I can see, what I know, and the changes starting to drag our profession in interesting new directions. I fear I may have muddied the waters, but hopefully they’ll settle and things will start to make sense.

Regardless of whether I’m right or wrong, one thing is for sure, these are exciting times and we have a great opportunity to finally leverage technical communications into the spotlight. The value of information is finally being properly realised, and we are ideally placed to help any organisation make the most of what information they have and help them understand and create the information they really need.

Re-reading the article I submitted to the ISTC Communicator magazine, I realise that my average day isn’t:

• particularly average at all
• a true representation of everything I’m involved with

I lead a team of writers so my typical day may not apply to everyone, and I also have a tendency to stick my nose in and get involved in other areas if I feel I can be of help. Simply put, if I hear someone talking about “information” my radar pings and I see if I can be of any benefit.

Other non-typical items include collation of Product Release Notes, my team proof-read Marketing brochures and website collateral, we try and monitor consistency in the UI of our customer facing product, and I’m currently in the process of creating (and managing) and developer community website. As an “unbiased” member of the development group I also recently facilitated our retrospectives.

One of the reasons I love this profession is that you can (and should?) be involved in many different areas. We have a unique view of the product and I guess my day is sculpted by that, although it is helped that we are a small(ish) company and have a small group of people thinking about the “product” as a whole.

I’m lucky that our company doesn’t have a traditional structure, with everyone encouraged to talk to everyone else regardless of role or level. It’s a little like a zoo sometimes, with a lot of noise and activity, but apparently that’s a good thing. It does mean I am involved in discussions that can be hard to be a part of otherwise, chatting to the Product Manager, Product Marketing and Sales, all of whom are saying the same thing, which in itself proves that things are working and that technical writers are a valid part of that discussion.

I’m curious to hear if others have the same opportunity; What other areas, outside of technical writing, are you involved in? And why?

How many times in your professional career have you been asked to spell something, or asked if a word is hyphenated? How many times are you asked whether to use “that” or “which” in a sentence?

We are the grammar police, the word monkeys, and many of us revel in that role (if not the title). Typically we possess greater information about writing than anyone else in the company, and rightly so as it is the main focus of our job.

However I am trying to stop answering these questions directly, instead I’m trying to direct people towards an answer. The reasons are two-fold.

Firstly it’s always better if people learn things first hand, helping to break the dependency for the future. In other words it stops people relying on you to remember things for them. It stops you being asked the same question, over and over and over. That can be annoying.

Secondly, and this is a subtle point, it re-enforces the notion that ALL we do is write words, that all we consider is grammar and spelling, that all we bring to a development team are documents. I don’t know about you but that’s not the case for me, never has been and never will.

It’s easy to quickly hand out information when someone leans over your desk, but maybe we need to be a little more careful. As (typically) a minority group in a software development team we have to work hard to prove and maintain our value, so maybe we need to distance ourselves a little from such matters.

I’m getting royally fedup with a lot of what I read that is written in the name of usability. Maybe it’s just a personal loathing of the overly academic, or perhaps I lean towards simplicity a little too heavily but SHEESH, some of the better known experts can’t half prattle on…

I’m a member of the usability team at work, largely because I made a lot of noise about it when I joined the company, but also because as a technical communicator who is passionate about the entire experience of using a product, I realise that the interface is THE most important part of communication between user and product.

I’ll let that one sink in, shall I?

Despite our own protestations, we all know that while good documentation is crucial to a product, it’s the user interface that carries the bulk of the load of communicating the capabilities of the application. With that in mind it makes sense to be as involved as possible with the design of the interface for, as I read somewhere many moons ago, we [technical communicators] are “the interface to the interface”. So, if nothing else, getting involved in usability and screen (UI) design for your application should make the job of documenting the software a lot easier.

Now, I’ll happily admit I’m still very much a novice in this area, but I’ve picked up enough knowledge over the years to be dangerous. I’m very aware that my advice tends towards what I would consider common sense, but generally speaking I base my UI design comments, and generally usability thoughts, on the following processes:

• Simple task analysis - picking out the main usage of the application should be pretty straightforward, but sometimes narrowing that down into distinct tasks can be trickier, so I tend to mentally “step back” everytime I approach a new screen and ask myself what it is I would WANT to be able to achieve given where I am in the application. Often you will find that the flow of the UI isn’t quite right.
• Narrow your view - the next step is to pick out each control to make sure the label, text or icon make sense. It’s very easy to get caught up in the overall task and presume too much.
• Quick, write something! - this step can be done mentally, with pen and paper, or just start typing. I often find that it’s only when trying to “tell the story” of how to use an application that all the pieces finally fall into place… and then you realise that one is missing.

As I said, I’m no expert but my approach seems to give reasonable results. Yes with formal analysis, metrics and so on, you can always improve things but sometimes perhaps good enough is good enough?

I sometimes wonder if I’m actually doing more damage than good so I’m quite careful that my opinion isn’t the only one (ok ok, isn’t the LOUDEST one), and I try and keep up with things - Boxes and Arrows & Jakob Neilsen for example - and I’m convinced that there is a big enough overlap between the two professions that one day I’ll be hiring a “usability writer”. No… a “technical usabilitist”…

The gaps in your documentation aren’t there because you haven’t consider a particular level of user; the gaps in your documentation are there because you haven’t considered how one level of user becomes another. How DO you get from Beginner to Expert?

The question above was prompted by a presentation I attend last week, given by Paul Sherman on behalf of the Scottish Usability Professionals’ Association, entitled: THE PERPETUAL SUPER-NOVICE.

The basic premise is:

the tendency of people to stop learning about a digital product-whether it’s an operating system, desktop application, Web site, or hardware device.

A simple example: Someone who has learned that you can cut and paste text in Word by using the Edit menu options and the application doesn’t support them learning how to do the same thing in a more efficient manner.

Many applications (and the documentation that supports them) is aimed at either getting from beginner to novice level, or getting from some kind of mid-level up to expert. There is a huge gap in application design (and, again, the documentation that supports it) around helping users get the most from their usage of an application.

That mid-level area is what Paul refers to as the Super-Novice:

in the absence of extrinsic motivation, it seems that many people stay novices or, at most, become a form of knowledgeable novice that I call the super-novice. Super-novices know a lot about the limited parts of a system they use regularly and almost nothing about the other parts

Obviously the presentation was focussed on usability and application design, but it got me thinking about how documentation, or perhaps we should be calling it supporting information, suffers in the same way.

It’s fairly easy to get into the mindset of the beginner; presume the reader knows nothing and assume a level of learning in which to frame the information. Expert level information is a little trickier but could be stated as specialist, or niche, information.

But what of the super-novice? If we want people to get the most from our applications (and we do, don’t we?) how do we enable the super-novices and help them become experts?

Paul touched on some of the aspects of web 2.0 communities, and how providing “achievement motivation” is a key method for enabling learning and helping build the “need for mastery”. At this point it is easy to see that traditional documentation, printed manuals or online help, will fail the user in this aspect. It simply can’t respond to the differing needs of the audience.

Of course there is still a requirement for those carriers of static information, but to really enable your users you need to start thinking beyond a simple push of information.

Looking at the current crop of social media networks and communities, it’s easy to pick out some common themes; there is always a core group of users who will soon become forum experts, reliable and helpful members of the group. These are the experts and the challenge is to help everyone else get to their level.

I’m still not entirely sure HOW one goes about that, but it’s clear that if this is an issue you can identify with, and that your audience acknowledges, then you need to start looking around for some new models of learning. The internet is full of them, just find a burgeoning online community and see how things work there and try and match it to your own audience.

The times they are a’changing, and those gaps in your documentation will only get bigger and soon, alongside the application, you may start to lose your audience. We need to consider those gaps, the line between A and B, and figure out how to help our users traverse it safely.

—-

Paul writes on usability issues (and more) on his blog, and for UX Matters where the origin of the presentation can be found (and from which the quotes in the post were taken).

As featured in the Spring 2008 edition of Communicator, the magazine for ISTC members.

I’m the Publications Team Lead at Graham Technology, a mid-sized (and growing) software company based in Scotland and like many people in this field, I have a wide range of duties. As well as the more traditional technical authoring work, I also manage resources, consider strategy and working practices for the team, and generally do my best to represent the user during development meetings. I also find myself spending time considering the information strategy of the company, investigating translation requirements, and keeping up to speed with the Technical Communications industry.

I joined Graham Technology just over a year ago and it’s my first time working in an Agile software environment. The development team use the Extreme Programming (XP) methodology and it’s taken a little getting used to, particularly as all my previous experience comes from more traditional teams, with long timescales, project managers with Gantt sheets and lots of process documentation to be completed.

There are specific challenges to working in an Agile environment and to a fair extent they shape my working day and, whilst everyday is different, they all start with the same thing. Caffeine.

I’m usually one of the first people in the office and, once the coffee machine is going, I take advantage of the peace and quiet to pick through the emails that have accumulated overnight. I monitor a variety of automated emails from different systems, all of which help me build a coherent view of what is happening during a release cycle.

We have a development arm in Jakarta so I take the time to sift through their work to check for any possible impact on the documentation. Anything that catches my eye is noted on an index card and stuck up on a dedicated whiteboard allowing anyone to see what is outstanding at any given time.

Next up is a quick check of the Publications build to make sure it has run successfully during the night. We currently use Webworks to generate Javahelp which is automatically compiled into the product each night; small changes are quickly actioned and committed to the documentation, and are then available in the next software build, keeping us in-line with the principles of Agile development.

The final set of generated emails I check are from our bug tracking system and they list what has been fixed or added in the past day. Again, anything that may impact the documentation is noted on an index card and added to the whiteboard. And, by now, the coffee is usually ready; milk and one sugar, please.

Last but not least, there may be requests for information that have come in from our Deployment staff out on customer sites. Sometimes all they need is a copy of a specific manual, other times it takes a little research to find the information they need. Once that’s done, I spend a little time skimming my RSS feeds for anything else of interest.

It’s now around 9am and the office is filling up. I typically have a few things to chase up from the previous day, and it’s a good time to have a few quick chats with the developers before they get too embroiled in their daily work.

Our Development Group is split into six distinct teams, with three technical authors covering their output from brand new features to bug fixes and product enhancements. Most of the teams have a standup meeting every day to take a quick look through the tasks that need to be completed, and during these I play user advocate, considering UI design and any information requirements that need considered. It’s a very dynamic and collaborative way of working.

Working within an Agile development environment means that things move fast and information flies in from all sorts of sources and directions. Monitoring email, changes to our internal Wiki, and chatting to the developers and testers in the teams are all part of a typical day. Placing yourself in the path of these streams of information is the best way to keep up to speed, and learn what is really happening on a day-to-day basis.

I also try and keep in touch with Marketing and Training to understand their plans and see if there is any cross-over with what we are doing in Publications. I’m striving to make our message more consistent, and improve the way we plan, design, create and distribute our product information, and maintaining direct lines of communication is crucial.

Part of my Team Lead role is to make sure the product documentation is meeting customer expectations. We have two products, a user-friendly out-of-the-box product which our Deployment staff extend using our development kit. Gathering requirements from the Deployment staff is a constant push-pull exercise and, as they are talking directly to the users of our out-of-the-box product they act as proxies who can be interviewed to make sure we are providing the right information, at the right level for the expected user.

The rest of my time is spent writing documentation. This is broken into three main types of work at any one time; small changes to the products which require less than half a day to complete, larger changes to the products which may take between a day and a week to complete, and documenting the brand new features that are being added to the product.

I start with a high-level plan of what is required and then trickle the information into the relevant document throughout the development cycle, handling changes in scope and requirements as they arise. I try and plan to work on small chunks of content, making it much easier to drop something if the requirement is descoped at any point (this is a key reason we are moving to single source our content) and I spend any additional time researching and learning the part of the product I’m working on, playing with the software regularly to make sure I fully understand both how it works and how it would most likely be used.

Like everyone else, I don’t really have a typical day. I do try and stick to plan for the first few hours but interruptions, conversations and changes of priority are all part of the challenge of working in a fast-paced software development company.

As we are in the midst of rethinking our publishing processes, I’ve been looking at the current crop of tools, and (for our needs) three of them stand out over their competitors. Adobe, AuthorIT and MadCap seem to be heading for a battle royale, with the latter two the David to Adobe’s Goliath. But who will win?

Before yesterday I wouldn’t really have put MadCap in that battle but it’s been a busy time for MadCap, who (yesterday):

..unveiled its roadmap for the first complete, native XML software family designed to solve all of a company’s documentation and authoring demands. The MadCap family will include five new products: MadCap Blaze, MadCap Press, MadCap Team Server, MadCap X-Edit, and MadCap X-Edit Express, as well as enhanced versions of MadCap Analyzer, MadCap Flare, MadCap Lingo and MadCap Mimic. The tightly integrated MadCap family will provide companies with an end-to-end solution for developing and delivering content in print, online and on the Web—and in their language of choice.

[full details]

OK, so MadCap have a lot of ideas, but what does this mean for the technical communications industry? Putting aside discussion on bespoke solutions, in what state is the current crop of “out of the box” products? And, ultimately, why is this news from MadCap so intriguing?

Looking at the current tools the obvious and dominating product is FrameMaker. Recently updated by Adobe and with a new lease of life alongside Robohelp in their Technical Communication Suite, the future looks bright for the product and as the market leader it’s a safe decision to adopt their products and, like Microsoft in the OS business, it’s safe to assume they aren’t going anywhere anytime soon. With a little work and additional tools, the Technical Communication Suite offers a smart multi-publishing system built around well-known and well-proven tools.

Then there is AuthorIT, which has been on my radar for sometime now, and the latest version certainly offers more functionality and builds on their core strengths. Their entire suite covers a lot of the areas that MadCap are targetting and it’s already being used by technical communications departments. The latest version is, in essence, a 1.0 so has a few rough edges and issues but the AuthorIT camp are making the right noises and I expect it to become a solid and viable solution for many people wanting to move into multi-format publishing from a single source.

At this point I should really mention the other tools that make up the rest of the market but as I’ve not really been heavily involved with anything else (Arbortext, ForeHelp, HDK are about it) it would be wrong of me to summarise both their market share and their futures (if anyone else has an opinion here I’d love to hear it in the comments). I would guess that, and I include AuthorIT and MadCap in this, the rest of the market outside of Adobe is fairly evenly split across a variety of products.

The new MadCap offerings bulk out their current product set into a complete end to end publishing system and, from what I can see with the limited details on offer, ticks all the boxes. On the other hand, both Adobe and AuthorIT will say the same thing so perhaps we need to see a little more detail before we get too carried away?

Yet, despite the fact that the feature set MadCap announced has a bigger overlap with AuthorIT, the feel is that MadCap are aiming squarely at Adobe. Of course, it’s understandable that they are aiming at the biggest target as chipping away at the other players probably isn’t a sustainable business plan, so the question is whether or not they can beat Adobe at their own game.

Given that Adobe were missing in action for a few years, the speed at which they have ‘caught up’ has impressed me but having seen demos of both their Technical Communication Suite, and of MadCaps offering (before these new products were announced) my gut feel is that Adobe have only caught up and aren’t moving forwards as fast as MadCap. In fact I think it’s safe to say that MadCap, and AuthorIT, are changing the game and I’m not sure if Adobe are properly positioned to respond.

As Ellis, over on the Cherryleaf Blog suggests:

I still have concerns that Adobe still really doesn’t understand the practicalities of technical communication, that features appear as solutions looking for problems to solve. However, Adobe is the market leader and, as we’ve seen in IT many times before, it’s often the company with the best marketing (rather than the best software) that wins.

The latest swathe of products gives MadCap a full, end to end, system that should be able to handle anything a ‘typical’ technical communications team can throw at it. In saying that, without a little more detail it may all be smoke and mirrors (something they’ve been accused of in the past) but the simple fact is that MadCap have already demonstrated they ‘get’ the current marketplace, and they’ve certainly made a big enough splash to warrant the attention.

I wonder, if we fast forward a couple of years, if the marketplace will still have one big player. I suspect not as the noises coming out of both the MadCap and AuthorIT camps speak of big things, so perhaps Adobe need to look over their shoulder and up their game? Regardless, the main winner of this competition is you and I, the technical writers who deal with these products on a daily basis. As far as I’m concerned, the biggest part of the MadCap press release is the fact it exists at all. Challenge the status quo and things start to happen, quickly, and the technical communications community can only benefit.