Let’s Confer

Two weeks ago I attended a conference (Megacomm 2012) that was aimed at both marketing and technical communicators. This was a whole day event and it got me thinking about the validity of this sort of bonus day out. Is it worth the cost to a company to finance their employees going to these conferences or is it a waste of their money. The said employee gets a chance to network, which in and of itself is a double-edged sword. He is as likely to gain something useful for his company as he is to find a new company.

I expect to gain very little in the way of new information, although sometimes it is useful to hear the “bleeding obvious” stated by someone else. On the other hand, I have a few years under my belt working for different companies, using different methodologies etc. so I regard myself as fairly savvy about the world in which I work. Others, with a smidgen less experience can gain quite a lot in the way of ideas – how others do things, confidence – they are not the only ones fighting with Microsoft Word numbering, specific problem resolution – assuming there are things that you find problematic, and of course lots of weight gain – the food at these events is (nearly) always better than the fare otherwise consumed in the workplace.

This conference lived up to all my expectations. Of the four sessions I attended, one dealt with documentation – becoming more efficient, one with training – converting documentation to courseware, one dealt with marketing analytics and one was a self-treat – how to best maximize free use of LinkedIn. My favourite was the training session, since it was so bad it ended up as funny. For example, during the session, someone asked a question to which the lecturer replied that all questions should wait until the end. Two slides later this same lecturer stated that a good presentation has to engage the participants via interactive questions and answers. Go figure.

The session outlining how to make the documentation process more efficient added nothing new to what I am already doing, but was extremely well presented and covered so many of the bases that it must have been brilliant to the less experienced. And even I need reminding of the “bleeding obvious” from time to time. This was definitely worth the time.

More and more documentation is being supplied in new formats, like YouTube videos or interactive wikis. Training is now often done via webinars instead of via a frontal course. So the marketing lecture on using analytics to see how well received your product/website/whatever is received by the outside world has a very practicable overlap with documentation trends.

All in all, it was a nice day out.

It used to be that I was against sending any of my employees to these things because of the lack of anything useful that could then be utilized in their daily slog. Now I realize that this type of bonus day out is exactly that. It doesn’t have to have a payback, but it is something that the employee wants and is thankful for, potentially increasing loyalty to the company and also giving an incentive to work better in the future.

So the overall verdict? A very acceptable waste of time, that does pay out dividends – go for it.

It just ain’t fair

If you ask a room full of technical writers what is their biggest challenge, I suspect that the number one reason would be the deadlines they are forced to meet. It reminds me of one of the two important lessons, both self-taught, that I stumbled upon as a youngster – always start complaining before you need to. This particular lesson was learned at school where I rowed in the first four. As part of the rigorous training imposed upon us was extra training sessions, which lasted over an hour unless we started complaining after fifteen minutes or so, in which case they lasted the hour but not more.

An aside: The other lesson I learned when about eight years old and made my bed for the first time. I did receive the praise I desired but was also told that since I now knew how to make a bed I could do it every day – not the reaction I wanted. And the lesson learned – never admit to what you can do unless you have to. This also has impacted on how I do business, as I have mentioned before. If asked for a document that I know will take only an hour to produce, claim at least three hours are needed.

Now this whingeing about deadlines wins us no friends. The product has to go out and as long as there is some documentation, the final dotting of Is and crossing of Ts does not help the sale of the product, even if we think they do.

There are two solutions to the problem of deadlines:

• Prove that the documentation is such an important part of the product that its production timeline must be considered when planning the product release cycle. For this to happen you must make sure that the documentation is a high standard and actually does help sales (as opposed to usage after the sale). You also have to convince product management and R&D of the worth of the documentation. I have managed to do this in the last two my previous three jobs, but it took time and hard work on my part to show the powers that be that I knew what I was talking about and that the documentation was as integral to the product as the installation program.
• Make sure you know what are the deadlines and how much wriggle room there is. Then plan your work around these deadlines, filling in the gaps in the product when writing about it when writing about it before it is completed. This requires a full understanding of the product, its use, the whys and the wherefores, etc.

Neither of these solutions are easy. But there again, neither are impossible. What is easy is whingeing and this gets you nowhere and gets the profession you represent a bad name.

So I don’t whine or whinge. Well actually I do have something to whine about at the moment. Recently many of the blogs I follow have had a post where they present a WordPress end-of-year report for their blog with statistics about how read they are in comparison to something that gives more meaning to the numbers. I never got a report from WordPress, so I had to come up with this blog, rather than a blog just regurgitating their figures.

Life is so unfair!

What else is there to say?

I have this blog site. I have subscribers to this blog site. I have a readership that extends past the subscription list.

Obviously I am doing something right. Obviously my pearls of twisted wisdom are making a difference somewhere. Somebody is reading what I say!

Last night we threw a party to celebrate my son turning thirteen years old. I wrote his speech for him, which was intended to be serious, something that was out of character for the both of us. The first line was meant to be a serious introduction to the speech. The audience thought it funny. They thought that this was intended to be an opening joke (possibly kn owing me better than I know myself).

Perhaps subconsciously I had phrased the line to be amusing – my subconscious is the rebellious region of my psyche that refuses to answer any question I put to it with a clearcut answer, so I really don’t know.

What I do know is that, sometimes, you say one thing and it is interpreted in a totally different way. You mean one thing and it is understood as exactly the opposite. You would think that writing for a living would have honed my verbal and written skills to the point where these misinterpretations and misunderstandings wouldn’t, even couldn’t, happen. And yet they do happen – go figure!

“The pen is mightier than the sword.” This pithy saying, coined by Edward Bulwer-Lytton, after many others had expressed something similar, is true only in the long-term, assuming you survive having your head removed from your torso by said sword in the short-term. What this means is that the words we write have a lasting impact. Not quite to the same extent as the words of a Shakespeare or Tolkien, but an impact nevertheless. And they remain around long after we have left this mortal coil.

So think twice about what you commit to disk – and more than twice before you publish to the ether. Once out there it cannot be retracted, so whatever you write has a permanency in this impermanent world way beyond what you thought possible.

And enough of this drivel for this week – what more is there to say?

It pays to be agile

It is not an information dirt track, it is an information highway, or even superhighway. And a highway means fast-moving. I spent my childhood in a world where Watch with Mother with Andy Pandy or the Flowerpot Men were the stars of children TV. Watching it now is liable to make you comatose. Those were the (good) old days where time wasn’t at the premium it is today. Bill and ben just wouldn’t cut it with todays children – not enough action! Not fast enough!

I don’t want to start a discussion about what lifestyle is better, since whatever the outcome of such a debate, the truth is we live in the here and now. Or did, since we’ve just moved on a bit more as I write these lines.

And as the world moves on, ever faster and faster, driven to a large extent, by the superhighway that now permeates every facet of our lives we, as the ones charged with explaining what is what, must move ever faster as well.

As a rule, we don’t sit in the driving seat, but if really lucky in the front passenger seat. If just lucky, in a back seat but more often than not in one of the trailing battered trucks that follow the developer supercar as he whizzes along the highway. And he is whizzing faster and faster.

Much development done today is done using the Agile methodology. In essence this is a style of development that hopes to get a product that answers the needs of the consumer out to market more quickly and efficiently than using previous methodologies.

Just as in traditional projects, Agile projects start with basic requirements gathering. Knowing the goals of your end users and project stakeholders is the necessary first step to any successful project. However, instead of trying to nail down all of the details up front, your goal in an Agile project is to capture just enough information to have a conversation with the customer at a later date.  You capture this information as short descriptions of the functionality in customer terms which you will flesh out shortly before development. Thus, you can avoid some of the overheads that are typical of projects where detailed requirements are gathered early, but often become invalid before the work begins.

During the development phase, there are short development cycles, between one and six weeks, with an end-product ready for release at the end of each cycle. The basic approach is to get-on and go. What is important is getting something out to the customer fast. If it only includes a subset of the customer requirements, this is OK – after all, it is better than nothing and in a few short weeks the customer will get another newer version with more features.

With this fast turnaround concept of development, including plenty of interaction between team members and between the teams and customers, there is little room for documentation. In fact the Agile manifesto states that the aim is to concentrate on working software rather than comprehensive documentation. Thus, face-to-face meetings and emails replace formal design documents and specs.

Since the product changes so rapidly, producing comprehensive user manuals, that becomes obsolete in the next cycle is a non-starter. Instead, the writer needs to concentrate on the bare necessities to ensure proper use of the product.

Minimalistic documentation has been around for years but now is its moment to shine!

Also, start thinking more and more out-of-the-box. For example, training materials can be merged with formal documentation or updates can be delivered via social media. The tweet “New folder feature in creation wizard: click Dir to specify folder.” becomes the latest documentation update. Nothing more is needed – no production, post-production, publishing, etc. A short tweet does the job!

Cut the verbiage. As George Orwell (of Animal Farm and 1984 fame, among others) stated in his treatise, Politics of the English language:

If it is possible to cut a word out, always cut it out.

Of course, that was OK for then. In the fast-moving agile world of today it should be written:

If it’s possible to cut a word, cut it.

Mix and match

The world is changing. Every self-respecting company has a Facebook page and uses it to push information to its readership. As people responsible for some of this information, we must also understand how to work with these changes to present our company and products in the best way possible.

My last couple of posts concentrated on a future where videos will take the place, to a greater or lesser extent, of the written word. This week I want to turn my attention not to the end product, be it video, wiki or whatever, but to the person producing this material and how he has to relate to the changing landscape.

It’ll be ready in a minute

“Please can you prepare XYZ, you have all the material.”
“Of course, you’ll have it in a few minutes.”

Actually, I’m willing to put money down that it will not be ready in a few minutes. if you want to hand over a good version of XYZ, even if it is just a case of extracting a couple of pages from a PDF, it takes more than a few minutes. After the extraction, which admittedly is even quicker than a few minutes, you need to check the properties to make sure the extracted pages are displayed as you want them to be displayed and not how Adobe decide they should be displayed by default. If this is going to a customer, it might require a cover page. If in the original there were cross-references that now don’t exist in the two page extract, these need resolving. Etc. A few minutes? I don’t think so!

So, firstly, a few minutes is never a few minutes. Give yourself some breathing space. You don’t have to take hours, but you do have to provide yourself with some flexibility.

Secondly, if you really can deliver in the few minutes you’ve promised, you have raised expectations for next time, when it won’t be as simple a request.

And then there is the other side of the coin, where you are the instigator:

“Please can you review XYZ, but bear in mind that it is just a first draft and I want to make sure I am going in the right direction.”
“Of course, I’ll read it this afternoon.”

Why is something that is not ready called “half-baked”? because when someone gives you a scrummy looking piece of cake, and tells you “it is half-baked so don’t expect too much”, you still bite in to the cake, expecting a major treat for your taste buds and are disappointed when you realize that, yes, the cake was well and truly only half-baked, and what you really need at this point is a spittoon.

So if you have something you want reviewed, or something that you think covers the main points as a starting point – don’t hand it over for the review. Just like the cake, the reviewer will look at your work-in-progess as the complete ready to release article and review it with this in mind.

The bottom line is to take the extra time to check your own work and make sure it is good enough in your view before handing it over to suffer the slings and arrows as others comment on your work.

And now it is time to be hoisted by my own petard. Last week I discussed using videos as the main way of presenting documentation. I decided to create a short, under ten minutes, video to demonstrate the idea. Of course, I am still learning this art form and produced a first draft using my voice and not a professional voice for the script. Also, there is background noise since I am not (yet) set up for this type of documentation. Also, there are lots of awkward pauses, that given time would be edited out or smoothed over. Also, the original was produced in a format that was not acceptable to YouTube, entailing a conversion using trial software. Also, …

So, you are now going to see, if you want, a work-in-progress, where, hopefully you will see how in approximately nine minutes you can learn how to create a blog post in WordPress. Obviously, for a demonstration, much is missing, but the idea is what I am trying to get across, even if it is only half-baked.

Click here for the video – but remember, as I hoist my petard, it is not a finished article by a long shot.

Seeing is believing

In numerous previous posts I have lauded the use of videos to supplement documentation. If a picture paints a thousand words, then surely a video must be getting close to a million!

After much thought and a few test videos, I am now thinking of reversing my position. Not that videos should not be produced as a supplement to documentation, but rather that documentation, in its traditional formats, be it PDFs or some form of online documentation like CHM or HTML help, become the supplement to the video. Thus, my new position is that technical writers should concentrate on making videos, which become the main form of documentation for distribution. I am not the first to tread this path, and where the idea has failed in the past is that it hasn’t included voice. Most video instructions I have seen include pop-ups with text to describe what is going on, which is restricted to simple statements. Often the video completely replaces the documentation, so I have to wait for the whole thing to finish to find that it didn’t answer my questions since this is the only documentation, I have nowhere to turn to get these questions answered.

What I am brashly suggesting, however, is to include the information that is still presented in a traditional format, as voiceover for the video. For example, when documenting an installation, you can create a video of the installation procedure but include an opening sequence where you check things like the available disk space, or other programs that need to be installed, or show the specific version of Windows, for example, being used in the video. The voiceover then includes the pre-installation requirements at the appropriate place, such as the number of bytes required to perform the installation and the number of bytes that are required to run the product. Again at the appropriate place, where you show the Windows version in use, you can list all the supported platforms.

There are, as I see it, two major problems with this idea. The first is the actual voice used. There are professionals who rent out their voice, but they are expensive. The second problem is maintaining the videos. A small change to the GUI can result in the whole video having to be redone and just rearranging the order that some parameters are displayed van mean another voiceover session to re-record the information for that point in the video.

There are tools available that enable dubbing parts of the video, so there is no need to chuck out a complete video when a small change is made, anymore than there is a need to chuck all the documentation. You can now, if you slice up the video correctly, replace just a few seconds of voice here and a few seconds of UI use there. So the problems are not insurmountable.

What is needed is a commitment to change. I really believe that if you concentrate your resources on creating user guides in video format, with less time spent on the written versions, you will find ways to make the process more efficient, until it is as natural and as efficient (or not) as the current system.

The truth, the whole truth and nothing but the truth

The product is ready and about to go out the door when the powers that be realize that it needs a few words to explain to the poor sap who buys it, how it actually works. So you are called in the create a users guide in no time flat. Not a problem, you have the fully functional and fully tested product to work with. Just be methodical and go through its usage for yourself and then transfer this to the virtual paper that the end-user will read and rely on.

It is almost as certain as the fact that the Earth is flat that the product will work exactly as planned. More likely than not, something unexpected will happen within five minutes of tinkering with it.

Another, similar, but different scenario is when you are asked to document a product during development. If you are lucky you have some written specs to use to gain a clearer understanding of what the final product will be like. But most probably, you’ll have nothing to go on except for a few conflicting sentences thrown out by different programmers and a non-working version to try.

In the second scenario you fulfill a dual role. That of technical writer as well as QA engineer, as you navigate through the bugs and blockers still in the product. Possible you also start to get involved in the user interface design, but that is another story.

Anyway, whichever scenario is your poison, you have to make some wild assumptions as to how things should work and take some educated guesses as to how you should document the damn thing. As I see it you can do any one of the following:

• Wait for the product to actually work the way it should.
• Write how you think it should work.
• Write how the company thinks it should work.
• Write how you think the company thinks it should work.

Of course, you are not in this business to do what you want, so you either write it how the company thinks it should work, if they indeed know, or tell you, or, as is more often the case, you write it how you think the company thinks it should work. The bottom line is that you are to a large extent competing with the likes of Tolkien for the title of best fictional writer. At least Tolkien knew he was being read!

My advice to you, when you find yourself facing this type of quandary is to get your hands dirty – go into the code. Get the versions being tested by QA rather than waiting for a clean build. Speak to marketing to understand what they think. Read all the white papers the company has written (unless you also have to write these). In a word dig! Dig deep to get enough material to write the basics. Extrapolate from what you have to fill in the gaps. Whatever else you do, don’t sit and wait for the product – because it wont wait for you and when it is ready, you must be ready with something reasonable: that is good enough.

We can’t write the whole truth because we don’t know it. Often no-one does. We can however write an approximation of the truth and hope that this is enough!

Never mind the quality, it’s the quantity that counts

One of the requirements for a successful blog is lots of hits daily. So a great blog, well written, informative, useful, that is not pushed, via Facebook, twitter, cajoling friends (and even enemies) is not a success. On the other hand, a blog that is really a disgrace to language and intelligence, seemingly aimed at the intelligence level of any slightly demented amoeba, that is pushed hard and has many hits, is a success.

Why do I care? I actually don’t, well not much anyway. I write this blog for my own satisfaction. If it is read by anyone more intelligent than the average Arsenal supporter, I am pleased. But I will continue to post, because it fills a need in me, whether it is read or not. And the number of hits that I get daily, does that interest me? Yes and no. I am more interested in what was hit rather than how many were hit.

I had a significant number or hits yesterday, many coming via searches. The largest number of hits came from searches for information about text alignment and justification, which turned up my Is style justified? post in the list of results, accounting for the hits. I have no complaints about this. I have a view on how useful justification is, just like I have a view about that hallowed technical writing bible the Chicago Manual of Style. Just because I don’t agree with what it professes to be laws written in stone doesn’t mean I can’t comment on it. And if people search for information about justification and alight upon my words of wisdom, so much the better.

One hit, however, was from someone who had searched for information about GPS. Now, my blog post about GPS, Finding your way – Is using GPS a good thing?, talked about the negative impact overuse of GPS has on the hippocampus as a way of introducing navigation as an important part of the technical writing process. You know the sort of thing I mean, a well designed table of contents, useful index, etc. The relevance to GPS was minor. I did, however include GPS in my tag list, so anyone searching for GPS might alight on my post. I did this for a number of reasons. Firstly, the opening part of the post I thought was interesting and was directly linked to overuse of GPS. So, anyone assessing my post did gain some information about GPS that they might not otherwise have known or found out about. Secondly, I knew it would increase the number of hits to my sight. You don’t need to be a rocket scientist to realise that GPS as a search item is going to be more popular than, I don’t know, what about hippocampus, for example.

Is it right to prostitute oneself for the sake of hits? And applying this to the world of technical writing, is it right to dumb-dowm the material to make it more accessible? To make it appeal to a wider audience?

Obviously, most of the time the audience you are aiming to reach is bounded. So reaching the masses is not relevant. But what about making the material more accessible? Just like including a tag to get a hit, which might help the reader, but just as easily might be irrelevant to him, including interactive material for example, such as quizzes or videos instead of tedious text to make the material more accessible, to get that extra hit, is most definitely a good thing. If you get more people using the product you are documenting by creating material that is not quite documentation but gets what you need to get across, across, then go for it. We enter the grey area between documentation and training, but anyway these are two sides of the same coin, so does it really matter which side falls up when you flip the coin? So dumb-down the documentation? Never! be creative in how you present the material? Definitely! Even if it means including the odd tag that is not too relevant to the subject matter.

And will I tag GPS for this post? probably not – I’m not as big a tag whore as the next blogger!

A comedy of errors

I’m a sort of sophist: Give me a topic and I will argue for either side. It makes no difference to me the rights and wrongs of what I am arguing, what makes the difference is the ability to put together a coherent, even if specious, winning point of view. I think that this is one of the reasons I like technical writing so much. You have to understand what you’re writing about from so many different viewpoints, such as the technology, the marketing take on that technology (wherein creeps in the specious descriptions that form the backbone of any introduction I write), and of course how the user will use the technology. What you write must then be a coherent synthesis of these often opposing viewpoints.

I can come up with an answer for most of what is thrown my way both in life and in my chosen profession, whether it be general questions such as should videos be incorporated within documentation, for those too lazy to read (and my answer is yes), or with more specific questions such as whether fields in a dialog should have a colon or not after the label (and again I argue the yes position). Where I have a problem is when it comes to the format of error messages. I don’t mean whether the error should include some kind of numbering system so that support can respond more efficiently, along the lines of AAAnnnnm where AAA identifies the module generating the error, nnnn is the unique error ID and m is the error severity. What I mean is what should the actual text of the message include?

Error messages inform you that an error has occurred. Some let you know why the error has occurred. Very few actually help you resolve the problem. So an error message such as “An error occurred while deleting the queries” lets me know that something is wrong but is not going to win any prizes for helpfulness. The error message “An error occurred deleting queries that were still running” is more helpful assuming I can identify the queries that are still running. I can then wait for them to finish and run them again. Better still, “The queries abc, 123, xyz are running and could not be deleted” saves me the trouble of finding out for myself which are the problematic queries. So where exactly do I have a problem with error messages?

Well, it’s whether to reword the error to include the solution, or leave that for the user to figure out. So instead of “The queries abc, 123, xyz are running and could not be deleted” the error could have been worded “The queries abc, 123, xyz are running and could not be deleted. Wait for them to finish running and then delete them.” But is this really a good idea? In the simplistic case I’ve used here it is a good thing, but errors are rarely that simplistic at source, and if they are they are only a small number within the bigger set of possible errors. So if I can give a solution do I, leaving the user frustrated when I can’t, or do I word the error message so that the user can work out what to do when that is possible and just suffer in silence when that isn’t possible.

It’s really about frustration levels. Errors increase frustration, so providing the solution with the message can reduce this frustration. However, when errors require a lengthy solution, or possible multiple solutions, or options which need to be tried dependent on the current situation, or … this is just not possible, and if some errors messages include solutions, the users expectations are raised, that all error messages can have solutions stated with the error, which is mostly not the case. Is it better to raise expectations and then shatter these expectations or not raise them in the first place? I don’t have an answer.

As a technical writer, also responsible for the clarity of the error messages, I work around the problem by keeping the error message as simple and concise as possible and creating and error guide to include all the potential solutions, with a get out line like “Contact support” for the messages that have no resolution that can be included in the error guide.