Switching from a very prescriptive style to a task oriented style is a mind shift for most writers, and whilst it’s one thing to understand the theory of something, making it part of your natural working practise is another.

Having read a few articles, and done some research into what task oriented writing is, I think I understand the basics, and have started to apply some of the principles to some of the stuff I’m currently working on. However I do find myself breaking out into the old functionality focussed method and I really need a way, a trick or hack or whatever, to keep myself think “task task task”.

Also interested to hear from anyone who has managed a team through such a transition. If you have any suggestions or thoughts, I’d really appreciate them.

Prompted by two recent articles discussing the use of a Wiki, firstly this one by Joann Hackos, and this excellent followup by Ann Gentle, I realised that my current place of employment is an excellent example of how well a Wiki can work internally, and how we are considering building on that success by creating an externally available source.

I can take no credit in the fact that the development team I currently work within has, and actively uses, a Wiki. I joined the company in January this year, and was delighted to find such a resource not only available, but being actively populated.

As an internal resource, the technical advantages of using a Wiki to capture technical information are fairly obvious. The ease of use, and open nature of a Wiki suit the task very well and I think it’s fairly safe to say that a lot of developers enjoy the lack of structure and formality as well. However, it’s one thing to have a Wiki, quite another to make it a central resource that is used without much, or any, prompting.

The key is to make the Wiki THE central resource for team specific information. With that in mind, most of our meeting minutes are posted there, as are seating plans, high-level feature plans and so on. Detail is kept to a minimum, and as they are using the Wiki to track their own work, it’s a simple next step for them to start populating it with any useful nuggets of information.

As for using a Wiki externally, I think Joann has the right idea. If you have a complex product, that can be used in many different ways and scenarios then, quite simply, you aren’t going to be able to document them all. It’s also likely that your users are going to have their own ideas and thoughts and, in some cases, your users may take matters into their own hands and start populating some form of resource of their own.

Wikis, forums and so on, considered the hubs of the social web, have shifted the power of information from the traditional model. Information is now considered free, and regardless of your view on whether or not that is true, the social web and, more importantly, the people involved within it, will pursue whatever they need to meet their needs. So, if you aren’t meeting them, and there may be valid reasons as to why that is so, as I mentioned previously, then perhaps part of our role in the equation is to become the faciliator in that area.

Of course, building an online community, regardless of how it is maintained, is no easy task. The beauty of a Wiki is that it is largely self-administrating, and you can rest assured that your users will automatically be predisposed to making it as useful as possible.

Creating and providing a Wiki to external users has an element of risk, and the biggest challenge may be convincing all the areas within your organisation that need to buy-in to the idea.

Do you use Wikis, internally or externally? Do you have a company blog? An online forum? If so, I’d love to hear your thoughts and experiences.

Additional info: How to hold meetings on a Wiki

The following is largely focussed on the software industry as that is where my experience lies.

I’ve been an on/off member of the TechWR mailing list for many years now. I dip in and out of threads depending on my current work and knowledge levels. The membership of the list is fairly wide-ranging, with people involved in all sorts of technical communication activites across many different industries. This gives any discussions around our profession and interesting slant as, by and large, the constituent parts of what it means to be a technical writer, and the daily activities involved, are somewhat tied to the industry in which they work. My experience is largely in the software world, but many of the other list members have wholly hardware-based experience, yet others work in highly regulated environments, and some flit from contract to contract, job to job.

A while ago a discussion about how our profession was changing kicked off and the range of responses was fascinating. This wasn’t a surprise of course, the list is full of passionate and intelligent people, but did have the effect of causing me to sit back and reflect a little more on what I do for a living and how, ultimately, it’s a fairly unique profession.

The discussion centred, mainly, around how the emphasis for a lot of technical writing jobs is swaying more and more towards a more integrated approach to the role and how it fits within a team than the historical basis of being heavily centred on writing. The presumption (largely being pushed by those of us in the software environments) is that the skillset a Technical Writer brings to a team extends beyond “just writing the docs”. As a customer advocate, we can (and should) influence UI design and the functionality of the product, and increasingly we are involved in the early design discussions, get hold of early builds and so on. To a small degree, today’s Technical Writer whilst retaining the core function of writing documentation, also dabbles in UI design, functional analysis, sanity testing software (note: this is not QA by any means!) and may even contribute to the software itself.

Some say that this detracts from the role for which we were hired. I disagree.

The role of product documentation is hugely important to any company and its creation will always be the core function of a technical writer. However, as companies push to reduce timescales and costs, whilst ask that productivity is increased, the idea of a closely-knit team with a shared vision becomes all the more necessary. Integrating a Technical Writer into that kind of environment means that speciality becomes less of an issue, and everyone starts doing a little bit of everything else. This extends beyond the Technical Writer, obviously, but uniquely we span the divide between technology and user (application and customer) and so can start to play a larger part in the development of the applications themselves, and also lessen the impact on our own area of expertise.

As I stated in that discussion:

I’ve always presumed that the role of technical writing isn’t really about ‘writing’ all that much (these days) and is why I’ve pushed to change job and team titles away from “writing” or “publications” to “communications”. It’s a small thing, but I think it breaks the “document monkeys” label a lot of people still have in their heads.

What this can mean is that a Technical Writer needs to have a sufficient knowledge to be able to intelligently converse with the application developers, and a good understanding of the business and user requirements that are currently being worked on. Acting as a “user proxy” in early design meetings has the double bonus of improving the application being developed (as most developers have a tendency to think in terms of functionality, rather than task) and hopefully easing the burden on the documentation as the general usability should be improved.

A bold statement perhaps, but ultimately the long-term aim is to have a better grounding in the usage of the application for which you are writing documentation. Understanding the why, and the who, as well as the how, is not a new thing of course, but contributing to the team in a “non-document” way is the real benefit.

A lot of companies still view product documentation, and the technical writers who produce it, as necessary evils to be tolerated and humoured. Most technical writers are able to constructively challenge and change that perception and I’m certainly not suggesting that anything I’ve suggested is the only way to do things. But I do believe that, in software documentation, there is a growing call for more technically technical writers, as opposed to technical writing writers. Becoming the accepted user-advocate in your development team is one path to achieving this, and I firmly believe that it will enhance both your own career and the perception of our profession.

Additional links: TechWR Mailing List.

From my own blogging experience, posting regularly is a good thing. Mr. Neilsen (who, despite reports to the contrary, is sometimes correct) suggests that quality not quantity is the way to go and, for this blog at least, it is something I’m striving towards.

Nailing a posting schedule is part of this and, as the evidence within demonstrates, I’ve yet to crack that egg. In an effort to force myself I’m going to try flipping that argument around for the time being and just posting whenever something catches my eye. No idea if it’ll make any difference but hey, you never know.

So, with that in mind, here are some interesting sites and articles that have zipped across my radar in the past few weeks:

• Simplest of style guides ~ “Write well, quickly, in the active voice and the present tense.”
• This way to the web, print designers ~ “… come to grips with the fact that, on the Web, design is not a method for implementing narrative, as it is in print, but rather it’s a method for making behaviors possible.”
• Is technical writing for you? ~ “If your goal is to write a novel, this is not the job,”
• Technical Writing podcasts by Harry Miller, a technical editor in Microsoft’s Developer Division User Education
• Adobe entering the “Office” software market? It’s a possibility, but what would it mean for FrameMaker I wonder..
• Better Writing through design from the “must bookmark” website A List Apart.
• Understanding Engineeers ~ “here’s a quick lexicon of what computer programmers generally mean when they’re talking about how hard some problem is” (via)

I hope you find them as interesting as I did.

Like most professionals I’m a member of various mailing lists, all of which deal with very similar issues, usually with overlapping people and discussions as well. The field of Technical Communications is wide and varied but there is always one type of query which is guaranteed to get a response… or 50 responses… sometimes more.

They are typically asked innocently enough, and at face value you’d think that most of them can be answered fairly simply and without too much back and forth. But, of course you are discounting one major factor, that holds true in many industries but does seem to be more prevalent in mine. Pedantry.

The vagaries of the English language are well-documented and far-reaching, yet time and again whenever any such question crops up there is an inevitable torrent of replies, most of which offer differing advice. When dealing with such queries, the one consistent recommendation is to pick your own way (of punctuating bulleted lists, or introducing example screenshots) and stick to it, but that is usually lost among the myriad of suggestions and arguments that arise.

Now, the title of this post is misleading because, of course, writing is a huge part of my job and if I couldn’t write properly … well I’d probably be out of a job by now.

However there is a feeling that, whisper it now, most readers aren’t that bothered about HOW we write, just that we write information that is useful and understandable.

You see, whilst a lot of technical writers studied English, more and more people coming into the profession come from a technical background first and foremost. Naturally this doesn’t mean that they can’t write properly but it does mean that the finer nuances and obscure rules of the English language might be lost on them. Or at the very least they might not even KNOW what verb construct they used in a sentence, but they will know that it scans and reads well, and that the user of the documentation will understand it without further explanation.

And yes, I lump myself into this ‘new breed’ of technical writers.

The minute one of those grammar/usage questions is posted on the mailing lists I cringe.

Partly because I know that a lot of terms that I have no knowledge of (nor inclination towards) will be used, and partly because, honestly, I don’t care.

Don’t get me wrong, there is a middle ground to be found. The best information in the world is useless if you can’t understand it, but equally the best information in the world is useless if it’s buried knee-deep in long, warbling, (if beautifully crafted) prose.

Good technical knowledge does not replace good writing. Similarly good writing does not replace technical knowledge but, within the software industry at least, it does seem like the latter takes precedence.

So, ultimately, writing isn’t that important.