Category: Work

Scott Nesbitt over at DMN Communications recently posted about mentoring and yes, I am quite flattered that I am mentioned…

I have been a team lead/manager at three different companies, cutting my teeth the first time as the youngest and most inexperienced member of the team at Dr. Solomon’s (the anti-virus people, bought by McAfee) standing in for a couple of months whilst a new department head was hired. Needless to say I didn’t do much mentoring there, as I was still largely learning my trade.

The second position was my best learning experience, with a small company that went through a couple of boom/bust cycles. I learnt a lot about myself, the role of technical communications within a software company and as I was hiring and building a team I spent a fair amount of time mentoring some of the technical writers I worked with.

But not all of them.

I’ve never been afraid of hiring someone with more experience, better knowledge or better skillset. Part of that is acknowledging my own weaknesses, and partly it is knowing that a good team requires the right people with a good range of complementary skills.

That said, I have worked with a few less experience technical writers and I do enjoy that process and the challenges it can bring. As I’ve recently been trying to allude, the considerations our profession requires can quite perplexing, and it’s good to talk through such things as, frequently, I too will learn something from those discussions.

So I guess what I’m trying to say is that I think that being a good mentor is as much about listening and learning as it is about guiding and teaching. I should really run this past my parents as they are both teachers and I’m sure will have a view on this kind of thing.

Today though, the role of mentor is fulfilled in a different way. We all have access (limited or otherwise) to some very very smart people in our industry, and whilst I do bemoan the noise on such places as TechWR, it’s true to say that I’ve learned a lot about what I do (and why I do it) from some of the people on that mailing list.

With that in mind it seems to me that the wisdom of the crowd is the new mentor, and that the next time someone asks us why we bother with blogs, twitter, mailing lists and so on, that that is the answer we give.

After all, everyone needs a mentor.

Continuing the terrible titles, this is a take on Catch-22, for no particular reason other than being able to play on the word “private”. Think yourselfs lucky I didn’t choose the schoolboy route and go with “Show us yer privates”.

Oddly the only reason I’m writing about this is because Twitter is currently dead, if it wasn’t then my comment on the issue would’ve been something along the lines of “@plasticbag – nice pic on BBC website! And don’t some people get in a tizzy sometimes..”.

At this point I should probably explain that I’m talking about the recently opened Fire Eagle service which

“… stores information about your location. With your permission, other services and devices can either update that information or access it. By helping applications respond to your location, Fire Eagle is designed to make the world around you more interesting! Use your location to power friend-finders, games, local information services, blog badges and stuff like that…”
[from Fire Eagle help page]

It’s a smart idea, and one which plays nicely into the fact my iPhone has GPS built-in so I can ping exact location information back to the Fire Eagle website at any time I choose. Clever.

But, of course, the privacy nutters (I use the term advisedly) have leapt all over this, stating that locational information could be stored by any of the 3rd party websites or applications that use Fire Eagle and then they’ll know where you have been!

Don’t get me wrong, I realise such things could be abused but from what I can make out Fire Eagle has considered such things. For starters they let you control the level of granularity of the geographic information that you share with other services, from pinpoint co-ordinates to a “I’m near this city” level location. Whilst you can purge your current location from the service at anytime, the privacy busters are more concerned about the historical information that could be stored.

Now I can see that will be an issue for some people, and that having a system know where you’ve been is worrying as it will, no doubt be used to guess where you will be at a given time and then… umm… yeah. Not sure what happens then.

Worse is the possibility of a hi-tec burglar watching out for your location changing before breaking and entering your house. These days I’d guess it’s not that hard to find an address for someone who looks rich, use Google maps to get the geographic co-ordinates of their home and then just wait until they update Fire Eagle with a new location (hey hang on, that DOES sound simple, eep!!).

Or, you know, if you are worried about it DON’T USE IT!!

And no, I’m sorry but the argument of “some people won’t know any better” doesn’t cut it. If they don’t know any better why are they signing up for a service they don’t understand? The Fire Eagle website does a pretty good job of telling people what it is all about so perhaps we need to shift a little responsibility on to the individual?

I’m sure some of you have stronger opinions on this topic than I do, I’d love to hear them. But be prepared to be mocked for, if I’m honest, I really don’t believe the end of the world is nigh because someone knows where I am.

It’s a common topic, an oft repeated complaint, and one which has already had many many lines of advice written, and countless suggestions offered. So here’s a new slant.

The reason most technical reviews fail is because of the writer, not the reviewer.

It’s not because the reviewers couldn’t find the time, it’s not because the reviewers didn’t understand the need or reasoning behind the review, it’s not because they didn’t know what to do, and it is most certainly not because they don’t value your contribution to the product and your part in the development process.

Because, if any of the above reasons are true, it’s YOUR fault, your responsibility.

Katherine Brown covers this area well in her recent article, noting that:

reviews can often go awry for a number of reasons at a number of points in the overall process:

• Poor communication
• Lack of preparation
• Lack of management support
• Unclear expectations and objectives for the review
• Insufficient time planned for the review
• Lack of follow-up
• Wrong people involved, or right people involved at the wrong time

Katherine goes on to offer solutions to all of these issues, but I have a different slant, namely:

• Poor communication – if, as a technical author, you cannot communicate there are bigger problems than the technical review!
• Lack of preparation – you are asking reviewers to give up their time, even if it is agreed many will consider this an ‘extra’ piece of work. Not preparing for this is likely to come across as both unprofessional and arrogant. If you don’t seem to care about the review, why should they?
• Lack of management support – yes, we do need to fight a little harder to get support for our work from management. No, it isn’t the way it should be. As professionals we need to learn to promote ourselves and, by our actions, gain the support we need.
• Unclear expectations and objectives for the review – as I’ve said, many people treat reviews as an interruption, so it’s up to you to make the objectives and requirements clear. What should they be looking for? What should they report back, and how? If they have a general query how do they present it during the review?
• Insufficient time planned for the review – as a project manager once said to me, there is no such thing as “not enough time” just something called bad planning. Yes you may need to fight to get allocated time (and you should, ad-hoc reviews are never as productive as well organised and scheduled sessions) but it is an important part of the technical publications process, so fight your corner hard.
• Lack of follow-up – It’s not hard to send a short email, summarising the main review comments or outcomes, to those that were involved. This is something I am terrible at but I know, when I’ve received similar communications, how well they work and how good they make me feel.
• Wrong people involved, or right people involved at the wrong time – “The more eyes the better” doesn’t always hold true. You need to figure out the best people, and make sure they are reviewing the content at the correct time, enlisting the help of your friendly project manager if required.

This may seem harsh but, and this is something I’m guilty of myself, there can be a tendency to wrongly apportion blame, to presume that the technical reviews are failing because no-one else is interested, or presuming that the work you do doesn’t need a review anyway (and you hate to bother those busy developers, right?).

We are responsible for our work, we are responsible for the information we produce and as the technical review is part of that production process (it is NOT a QA check!) then, if it is failing… well, I’m sorry, but it’s your fault.

I have a MacBook, and I really enjoy using it as it is a very nice experience.

I have a PC, and I really enjoy using it as I am a power-user and have it tailored to the way I work and I’m very comfortable in the environment.

I find myself wanting to use the Mac for more but as I’m still learning keyboard shortcuts I find myself pausing and.. well it’s still not as fluid for me as working on the PC. Part of that is the resolution of the MacBook screen which is, these days, rather low. Hence my recent ponderings about a KVM to allow me to hook up the MacBook to my LCD monitor.

Anyway, another thing that stops me switching fully to the MacBook is the pitiful hard-drive. My music collection ALONE, is larger than the drive which brings me to the topic of this blog post.

I think what I need to do is switch out all of my storage needs, files, photos, music, to an external drive. That way it doesn’t matter what machine I’m on, I can just switch the external storage drive and access whatever I need.

So I just need to figure out how to move the iTunes library files to an external drive and I’m all set, I think… Ohhh yeah, and buy a big enough hard drive (and backup).

Or maybe buy an iMac… hmmmm

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.

“We should test the documentation”, seems like a harmless enough statement and I’ve heard it uttered in more than one place yet I’ve never worked in a company that actually tested the documentation.

Some clarification is usually required, of course, as there are many ways that you could test the documentation, for example:

• For online help, test that any hooks from the application to the documentation work properly
• Check that cross-references are corrected and, if hyperlinked, work properly
• Test the content matches exactly what is on-screen
• Test the flow of information is correct and makes sense from a users point of view

Now, we do test that our online help works correctly, that the correct page is launched from the application and that a sampling of internal links work correctly.

However, the last two items in the list can be a bit of a thornier issue. Testing the content is a much bigger job than most realise, presuming it is being done correctly and it also raises the fun issue of is this a bug in the documentation, or in the application.

Every time I’ve had this question asked I’ve said yes we should test the documentation, but what I really mean is that we should use the documentation to test the application. One method I’ve thought about is to have one person would read out the instructions, with another piloting the application. Just an idea but it would flag up some issues in both areas, I think.

Of course such resource heavy requirements rarely see the light of day and the simple fact is that we don’t test the content of our documentation. Yes we get it reviewed but they are separate (if closely related) things.

So, in an effort to close the gap between reviewing the documentation and testing the documentation, it is probably worthwhile running a short workshop for your development team, a 10 minute session that shows how best to review documentation. I’m planning such a workshop at the moment, so more on that, soon.

Anyone working in the software industry will know the term “usability” and have a reasonable idea of what it entails. As a technical writer, a user advocate within the development team, there is typically an overlap between how we think, and how usability specialists think.

For starters, anyone who is delivering information should know who their audience is and why they require the information. With a good understanding of your audience, you will know what information they require because you will understand how they use your product.

It seems obvious yet it’s something that many people struggle with, and I wonder if it is partly because, rightly, usability is a distinct field which has many experts and practitioners.

However, many software companies do not have resource dedicated to usability as, and I don’t get to say this often, it’s often seen as less of a priority than technical writing.

Why does any of this matter to you as a technical writer? Because it’s another string to your bow, another item to add to your CV, and something else that will convince your boss that it’s worthwhile keeping you in the team.

And hey, it’s interesting stuff, a little task analysis of the requirements, some creative thinking, and an even better understanding of the product and then, if you are really lucky, you get to talk directly to users of your product.

I’m part of the ad-hoc usability team in my company, and whilst it can be challenging it is part of my job I hugely enjoy and which makes me a better technical writer, and that’s never a bad thing.