DITA Is Not the Answer

Single sourcing is good, I’m sure most of us can agree on that, but I’ve recently been wondering if perhaps DITA isn’t quite good enough?

McLean, Gordon. One Man Writes (2007). Articles>Content Management>XML>DITA

Everything is Connected

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.

McLean, Gordon. One Man Writes (2008). Articles>Content Management>Content Strategy

Getting to Expert

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?

McLean, Gordon. One Man Writes (2008). Articles>Documentation>User Centered Design>Technical Writing

Testing Documentation

As part of the product, testing documentation seems like an obvious thing to do, but what does it really mean? I’ve fielded the question in a few different places now and it’s always interesting to delve deeper and understand the rationale behind the request.

McLean, Gordon. One Man Writes (2008). Articles>Documentation>Assessment>Testing

Driving Development

By partly adopting the process suggested by Daniel Brolund we, the technical writing team, can be involved right up front and the documentation can be one of the methods used to validate the software as it is being built.

McLean, Gordon. One Man Writes (2008). Articles>Documentation>Writing>Technical Writing

Revisiting the Basics

There are some fundamentals tenets of our profession that are widely accepted. One being that you always need to know your audience before y can begin to understand their needs and so produce the information that they require.

McLean, Gordon. One Man Writes (2008). Articles>Writing>Technical Writing

Does Single Sourcing Content Work?

One of the more popular posts on this blog is titled DITA is not the answer and, whilst things are certainly moving forward, it’s a little sad that it is still valid. A recent comment on that post suggested that it’s not just DITA that is lacking, it’s the working realities of single source that is flawed.

McLean, Gordon. One Man Writes (2009). Articles>Content Management>Single Sourcing>DITA

The Black Art of Estimation

Estimating the amount of time it takes to write documentation is tricky as it relies on many differing, subtle, factors and, for many people working outside of a highly regimented and heavily project managed team, it tends to boil down to a mixture of guesswork and experience. However, it’s not impossible to come up with a more reasoned estimate as long as you don’t mind doing a little planning.

McLean, Gordon. One Man Writes (2009). Careers>Documentation>Technical Writing>Estimating

Designing Websites

The parallels between the theories of technical communications and those of web design are very similar, the key aim is to keep the audience in mind at all times. The way you structure and present the information is also important, as is a sense of usability of the content itself.

McLean, Gordon. One Man Writes (2009). Articles>Web Design>Technical Writing>User Centered Design

Bye Bye STC

Perhaps the time has come to wrap up the STC and let a new organisation grow from the ashes. Those who are interested, and who believe our profession needs such an organisation will rally round and rebuild something. If there is not enough interest then perhaps that is a further indication that the STC has had its time.

McLean, Gordon. One Man Writes (2009). Articles>TC>Community Building>STC

Pick a Card

There are obvious benefits to single sourcing, the ones that roll off the tongue the minute single source is mentioned: multi-format publishing, consistency of information, quicker updates of common content, lowering translation costs and so on. But beyond all those, what else is there? In this guest blog post, Gordon McLean discusses just that.

McLean, Gordon. DMN Communications (2009). Articles>Content Management>Single Sourcing>Documentation

What do the Users Really Want?

I have no idea what our users want. I do know they want information, and I know they want that information to be kept up to date as our product evolves and as far as those basic needs are concerned, I’m happy that we are meeting them. Beyond that I admit I’m not really that sure.

McLean, Gordon. One Man Writes (2009). Articles>Documentation>User Centered Design>Surveys

Dumping the Manual

I honestly can't remember the last time I picked up a user manual, an honest-to-god paper book of technical documentation. Actually that's a lie, it was just last week when i was tidying up. I picked up several user manuals and moved them to a lower shelf on my bookcase. So why do we still maintain a traditional view of how information should be provided?

McLean, Gordon. One Man Writes (2009). Articles>Documentation>Online

On Taking Notes

I have been remiss at writing new content for this blog, and whilst this topic isn’t one that I said I’d post about (those posts are coming, I promise), it’s something I was discussing yesterday and so is at the forefront of my mind. Like many people I still use pen and paper when taking notes, and regardless of the type of meeting I stick with three basic categories.

McLean, Gordon. One Man Writes (2009). Articles>Interviewing>Writing