I’ve been chasing this train of thought for a while now and decided to start writing my thoughts down in the vague hope that they come together in a way that makes sense to others. It seems to make sense to me but, as yet, there are a few grey areas into which I may stumble. So, not so much a train of thought but a car crash of ideas, if you will.

Shoddy metaphors aside, the main crux of my thinking is based in my efforts to find a central point around which I can arrange my knowledge. Obviously my knowledge of some areas is greater than my knowledge of others, but part of this exercise is to start to identify the areas in which I’m lacking and so allow me to investigate them further, to feedback into my train.. no.. car… umm, driveshaft??

OK, let’s start over.

The role of a technical writer is fairly varied, and merrily traipses through several distinct fields. Most technical writers will know a little (or a lot) about many topics, how to structure information or how to create a usable index, they will be also have some knowledge or awareness of, for example, typography and readability issues, they will have some knowledge of working with graphics, and they will also gain knowledge of the various tools they use. Suffice to say that the skill set and ‘earned’ knowledge a technical writer posseses is almost endless.

And that’s all before you consider how much they know about the products that they are documenting

So from that starting point we can see that technical writers already dip their toes into various pools of expertise.

Now, let me just changes hats for a second… right. I am now a web designer.

Look at the knowledge I have attained as a technical writer, with a web designer hat on, there are a lot of parallels. Some are direct, some not so obvious but still discretely linked, after all, regardless of the medium the two disciplines share key facets of importance; content and audience. The delivery mechanism is secondary to those at all times.

Web designers also span several different fields, with some knowledge of HTML, CSS and other languages (usually text based), they too worry about layout and typography to ensure readability is maintained, they plan what type of content will be created, and understand the need to structure that information in such a way that it is explorable. The parallels are many.

So, somewhere in my head I’m wondering why the two disciplines don’t seem to be talking to one another. Is it lack of visibility? Is it just me that thinks it is this way? Are there secret meetings going on as I speak?

One of the reasons I ask is because there is a wealth of information out there that focusses on web design, even spilling over into the social/community aspects of information sharing, which the technical writing world could use and leverage. Have a look at some of the articles on A List Apart, for example. Those which aren’t specifically about code tend to talk in terms of analysis, planning and design. All things I do as part of my job as a technical writer. Boxes and Arrows takes you into Information Architecture territory, with user experience key and, for many of us who work in software development and who can influence both the UI and the Use Cases that help constitute a software application, there is a lot of useful information that we can adapt for our own use.

If you are in New York City in early October, check out the idea2007 conference, which will highlight and discuss designing complex information spaces of all kinds. A limited entry pre-conference event kicks things off on the 3rd of October, and the conference proper is on October 4th and 5th.

Throughout their days, people are engaging with complex information to manage their lives.

And designers now realize that information isn’t simply this stuff you find - the appropriate presentation of information helps people make sense of the world around them.

This conference addresses issues of design for an always-on, always-connected world. Where “cyberspace” is a meaningless term because the online and offline worlds cannot be made distinct. Where physical spaces are so complex that detailed wayfinding is necessary to navigate them. Where work processes have become so involved, and so digitized, that we need new processes to manage those processes.

This conference brings together people who are addressing these challenges head on. Speakers from a variety of backgrounds will discuss designing complex information spaces in the physical and virtual worlds.

Keep an eye on the conference blog for further snippets.

I’m a member of the IAI and a little disappointed that I won’t be there, I’ve also been helping out on the conference website (although it’s a bit cheeky to claim that as my contributions have been few and infrequent).

The following is taken from current experience, fitting a Publications team into an agile (XP) development methodology. It’s very much a work in progress…

~

In a more traditional development environment, there is likely to be specifications and design documents on which you can rely. This is not the case in an agile development environment, with requirements focussed around user acceptance, and a heavy reliance on word of mouth (through pair programming) and shared knowledge. It may sound chaotic, it is not. Each piece of functionality is assessed and if there is not a direct requirement for a piece of functionality it doesn’t get done, similarly each piece of functionality is stated as a story, and will have an index card created which can be used to track the story through various stages.

To match the pace of software development, the Publications team needs to adopt a similar approach. Rather than waiting on information to come to us, we need to be involved, engaged and pro-active in learning and understanding what we are documenting, and breaking out of the old authoring model.

Previously large chunks of documentation were written by the same person, often at one sitting. You’d outline a chapter and start bashing in the words, investing a lot of time and effort into your ‘baby’. That concept is no longer applicable.

The trickle method relies on the ability of the technical author to retain a “big picture” view whilst working on multiple chunks of information at any one time. The information will not come in a set order, nor from a definitive source, instead it will trickle in from various parts of the development team, testing, and so on. Your job is to monitor the flows of information, position yourself within a stream (or two) and divert the information you need into the documentation.

As such, the technical authors will be sat within development teams and are expected to attend all designing and planning meetings. Understanding as much of the work as possible, as early as possible, will benefit the documentation, and having a technical author in place at the beginning of the development process will benefit the product. Be the user advocate, keep the tasks they will be performing in mind and strive to contribute as and when you can.

This way of working is different, and does mean you need to adjust your mindset somewhat.

You will not:

• Be able to write entire sections in one go.
• “Own” the document you are working on.
• Always finish what you started (but only if it’s planned that way!!).

Hopefully this new approach will make us much more involved in the day-to-day development of the product, and by bringing additional benefits to the development team, will increase our standing with them.

I like new things, as my Belbin team role suggests, I am the person who likes to start projects and enthuse others about it before… eventually.. I get bored with it and… ohh shiny! .. something new comes along.

I’m aware of this trait and have developed some internal habits that help me overcome it’s downsides, in other words I’ve figured out when I’m getting bored and so I start to change how I work to make sure that I see the project through to completion.

However my enjoyment of new things is beneficial and I’m constantly looking for new ideas, new inspirations from which I can learn, and for ways in which those ideas can be cross-pollinated (ok ok, stolen) and used in new ways.

One example came about when I first picked up on, after many years of being told to read it by my peers, Malcolm Gladwell’s book The Tipping Point. It’s a fascinating book and several of the key points can be translated into the technical writing world. One in particular stood out, the premise that an idea could be made ’sticky’, and got me thinking about how I could adapt some of the methods into my approach to writing and structuring documentation. To my great pleasure that premise has been further developed by Dan & Chip Heath in their book Make it Stick and, although I’m only partway through it, I already have some ideas which may help make the documentation I create more useful to the readers.

There has been some discussion about our profession recently, whether it’s “just a job” or a vocation for some. I think I, like others, fit somewhere in the middle. Whilst I doubt technical writing/technical communications can be seen as a vocation, it’s certainly more than just a job to me, spilling over into my everyday life and thoughts. Typography, design, architecture, marketing and, basically any form of communication, has me questioning and prodding it to see if I can reuse any of it.

These days with personal publishing also a hobby for many, myself included, obviously, then anyone who is interested in communicating ideas and information is able to draw so much from such a wide pool of sources that, and I hold my hand up in admission here as well, I’m somewhat surprised that we have been a little slow to grab onto these new ways of communicating. Mind you, blogs, wikis and the like, are all still very new so I expect that to change over time.

But it won’t stop me constantly scanning the horizon for something new.

Have you taken inspiration from an odd source? Spotted a clever way to tackle information, or noted an idea or two after reading a, seemingly, unrelated book. How much of a magpie are you?

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?

The basic premise of “single source” can be summed up in one word.

Re-use.

Sounds simple enough but there is a wealth analysis and work that is required before that, somewhat elegant, aim can be met.

Analysing your content for potential re-use opportunites is, by and large, an onerous task. Whether you do it all by hand, printing out reams of documentation and annotating by hand, or electronically compiling spreadsheets using colour coding or obscure (”they made sense to me at the time”) codes, it takes time to do it properly and there are no shortcuts. Sorry to break it to you so bluntly.

However it does mean that you are forced to spend some time re-reading your content, content which you might not have visited for some time or in some cases, may not have written yourself. You’ll likely find inconsistencies in the content itself, styling errors and quite probably a completely different writing style. Whilst it may seem obvious I urge you, should it arise, to fight the urge to start editing as you go along.

My basic understanding of single source, and the re-use of information, is that there are times when you’ll need to rewrite content so it can be easier used in multiple locations. A change of tense perhaps, a rephrasing or reconstruction of a sentence may be all that is required, and hell, if you have the document open in front of you, why not just go ahead and make that change? Suffice to say that editing content that you are analysing has only one potential outcome. Chaos. Regardless of how well organised, how well planned your analysis is, if you start making changes to your content on the fly, you will soon find yourself with a blurred view of the very thing you are trying to analyse.

Yeah, I know. It’s sounds obvious, and it is when viewed from a distance.

However what I really wanted to discuss, for I’m certainly not 100% certain on this, is at what level does content granularity become too granular? If I want to re-use a paragraph then, obviously, breaking up content to the paragraph level makes sense but that immediately seems like overkill in many cases. So I’ve been steering away from that kind of structural thinking, away from paragraphs and sentences into semantically discrete blocks. So a short product description, containing a heading and a paragraph, is one block and a long product description, containing a heading and several paragraphs, is another. I’m pretty sure this is the correct approach but it does mean that, once you’ve made that decision, you are stuck with fairly large chunks of information.

I’m hoping that this is a good balance though, for if we are to break our content into smaller granules, the overhead of maintaining and manipulating them surely increases. Remember, in a single source system we are concerned with more than content, we also have to contend with the metadata associated with that content, and the more pieces of information we have to maintain, the increase in risk that the metadata becomes so complex as to be useless?

I think. Maybe.. I’m really not that sure.

Have you conducted any content analysis? If so how did you approach the granularity issue? I get the sense that, for a lot of people, the level of granularity is reached once the content analysis is complete, that it basically decides itself.

As we slowly progress towards a single source solution, I’m intrigued as to what to expect next, any thoughts or comments are much appreciated. After all, all the articles, conferences and books in the world can replace real life experience.

Notes:
This post was, in part, inspired when pondering if semantic analysis might be a way to tackle this but, for now, I wonder if it is perhaps a step too far for most?

Audience, audience, audience.

A simple mantra, and one which crops up in most technical writing discussions at some point. If you don’t know your audience then how do you know what to write, and why you are writing it?

Most technical writers will be aware of the particular audience for the document they are working on, but as part of understanding WHO the audience is, we must also have some knowledge of WHAT they do, or don’t, know. But how far can presumption take us? If we don’t have access to our users to perform a thorough user analysis then we are, at best, guessing. Even if it is in a very well-educated way.

Of course understanding WHY someone is using your documentation goes a fair way to providing a basic framework upon which you can base further “guesstimates” as to what information your readers require.

With this in mind, I have long since used the following general presumptions. I will stress that they are no replacement to actually talking to users, but they can help focus early discussions in a project.

My suggestion is that there are at least six key phases, or touching points, during which a customer will be interacting with your company and the information you provide. Touching points are not always direct, may not always be pushed out to the customer, and they may not always be followed in a linear fashion, as they are entirely dependant on the needs of the user.

Naturally the specific Touching Points within your interactions with customers will differ, but it’s a good exercise to step back and make sure you’ve captured them.

First Touching Point
The first time a customer hears about your company. This may be because:

• They have a pressing business need and their research brought them to your website.
• They attended a Trade Show, and received your marketing literature.
• You are following up on a potential sales lead from another project.
• They received a recommendation from a colleague.
• They have worked with you before.

The information requirement at this point is largely high level and business focussed. It’s more than likely that the information will be consumed by senior management, or perhaps used by middle-management as part of a briefing to senior management.

Second Touching Point
The customer is aware of your company and your products, and has a basic understanding of what is offered. They are looking for more information to allow them to make the necessary business decisions: Will this product meet our business need? Does this product offer a good ROI? Is our business ready to adopt this product? Does this product meet the regulatory requirements our company operates within?

The information requirement remains business rather than technically focussed, but has some aspect of product documentation available, an overview of the product capabilities and the underlying requirements and prerequisites.

Third Touching Point
By now the customer has decided that your product is viable for use within their business. You need to make sure they are fully aware of the implications of purchase, and of any additional requirements that their specific needs may drive.

They need to raise a business case and start the purchasing process.

Largely driven by Sales, the information here may be pulled from a common pool, with the prerequisites driving the information itself.

Fourth Touching Point
The customer has bought the product, and the deployment phase has begun.

For a custom solution, the bulk of the information needs to flow through a deployment or solutions team, as well as being usable by the customer throughout the lifespan of the product. This touching point is key during this stage as a lot of the information you will provide at source is likely to be edited to match customer needs. For an out of the box product, the information is centred around product functionality.

Fifth Touching Point
The product is deployed on the customer site. You are now in the support phase, and the need to be able to handle usage questions and more advanced requests for specific information.

Information requirement is largely customer driven but may still be pulled from various ad-hoc forums and FAQs.

Sixth Touching Point
The customer is transitioning from one version of your product to the next, or between products.

As a starting point, I think this approach is valid, and I’d be interested to hear if you have made similar assumptions. I wonder how often we document products without any insight into the audience whatsoever, and if you have done so, I’d love to hear how you tackled it.