I recently received an email which asked:

Since my career seems to be following a path broadly similar to yours … I’d love to know what your experience was and any lessons learned.

Specifically Mark, who sent the email, asked a few questions:

1. How do you take over as manager for a group of technical writers?
2. How do you get better management buy-in (promise cheaper or faster dox?)?
3. What are the first activities you should do (content audit, benchmarking?)?
4. How soon is *not* too soon to start changing things?

I’ll break each question out into a new post so, without further ado, onto question #1.

How do you take over as manager for a group of technical writers?
Carefully!

Typically if you are joining an established team then it pays dividends to take your time to settle in, understand their working processes and day to day habits. It’s fair to presume that they have a set of processes that work for them and that are tailored for their environment. That’s not to say that those processes couldn’t be improved but avoid being brash and making changes for the sake of it. You got the job, you don’t need to ‘make your mark’ by changing things the minute you get in the door.

I’m not sure if I have a management style per se, but I do try and be as open as possible. If I don’t complete a task I say so, and if I hear something that the team might want to know, I’ll tell them. Beyond that I let them manage their day to day activities and try and make sure that my role only extends as far as pulling everything together into a cohesive view across the entire documentation set. I strongly believe that a good manager is one who removes obstacles and deals with issues, whilst promoting his team at every opportunity. I’ve been lucky that the team I currently have are diligent and motivated, all I really do is guide them when they need it.

As a new manager it’s important to quickly build relationships with everyone with whom you’d like to be involved. I’d suggest that that typically means almost every area of the company. A short introductory meeting with each manager or team lead is usually enough, a quick chat to outline what you are trying to achieve with your team, and how it may benefit them. This is largely the beginnings of managing the expectations of what your team can bring to a company, as well as building some bridges.

Currently I have good ties into Sales, Pre-Sales, Marketing, Training and our project staff. It can be tricky keep everyone up to speed, but the benefits of having a consistent message is an easy one to sell. These introductory meetings also allow you to re-instate the position of your team. Previously it may have been the case that “ohhh we don’t talk to Marketing” but you can use the fact that you are new to break through the socio-political barriers, after all, you don’t know any better, do you?

Gaining buy-in from your team is the main thing that you need to figure out. Taking a soft approach when you first join, making sure that you are learning from the team and not dictating things is important. Ask questions by all means, sometimes a simple question might prompt the team to realise something they had noticed (aka the ‘can’t see the wood for the trees syndrome’) but it makes sure that you are seen as a team player.

Finally you need to understand the business plan. Ultimately part of your job is to make sure that your team is contributing towards the goals of that plan as efficiently as possible. You will have other expectations and agreed deliverables, and understanding the business plan will allow you to make the right decisions both for your team and for the benefit of the company.

Once you understand all of this, your position, and the position of your team in the company, you can start to formulate goals and aims. Setting a high level vision for where you want to take the team can be tricky but if you have spent the time gaining their trust and buy-in, you should be able to collate all of that into a vision that everyone agrees. Once you have that, revisit your colleagues that you introduced yourself to and update them. Set out the expectations for the coming few months and get going!

Cherryleaf will soon be publishing the results of their recent survey of Documentation Managers* and, having skimmed through a preview, the main thing that leaps out at me is that the field of Technical Communications in the UK remains as diverse as ever in many respects, yet completely the same in others, and none of that is a huge surprise.

Whilst we all may use different tools and approaches to our work, we all feel under the same constraints of time and resource. However the results do throw up a couple of issues and, as one of the participants of the survey, I thought I’d expand a little on one of those.

The survey hints at two issues:

1. “The documentation teams generally continue to use authoring tools exclusive to the team … Content from 3rd parties, in most cases, needed to be … imported into the authoring system.”
2. There was little evidence of any moves toward a company-wide approach to sharing and managing intellectual content.

I don’t think the first is a contentious statement but what interests me is the phrasing. The implication is that technical writing teams are seen as (or see themselves as?) content consumers, areas of the company into which content is lost to proprietary tooling. Obviously we publish a lot of content but perhaps we are a little too guarded of the information we collate?

I’ve never had an issue sharing information, regardless of state, as long as the appropriate caveats are in place. Information is meant to be shared, so the more of it we do, the better. In my opinion.

More interesting is the second point around the lack of evidence of company-wide information management. This is something I’ve been working on with key members of other areas of our company, and from previous experience it’s usually the technical writing team that takes a lead here as we gain the most benefit from having a good information management solution in place.

That may boil down to a document management system (from ad-hoc to access controlled repositories), or even a content management system, but ultimately the benefits are applicable across entire organisations. I’m lucky in that there are a couple of people who see the benefits and so it’s much easier to drive adoption and cooperation across the organisation, but even if that weren’t the case, and in the current climate, it may be something you should look into and start to drive forward yourself.

The survey results are, like any survey, a thin sample of our profession in the UK, but it’s great to have that information available. I’ve already spotted a few things that I can use in discussions within my own company, and there are plenty of common themes and ideas that can be carried forward to help improve our team.

So, well done Cherryleaf, I’m sure it wasn’t an easy process but I certainly think it was well worthwhile.

* A coverall title that encompasses anyone responsible for a team of technical writers.

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.

Well, that and the fact that I keep referring to single source when I am actually meaning content reuse (for you can have one source for everything but not reuse the content anywhere).

You can read the full comment yourself but the relevant bits are:

I have never seen single sourcing work. Maybe a single author who knows the topics thoroughly enough to reuse, or a tightly knit group of writers synched up at the same level.
…
The only place we are going to reuse content is in web mashups using semantic markup once the content is in the cloud.

It’s an interesting view and one which touches on something that has been on my mind these past couple of weeks as we are in mid-migration towards our single source solution.

Just how do you coordinate a team of writers, working in discrete areas of the documentation, with a large number (3000+) topics?

There are a number of ways we are tackling this and only time will tell if they are successful. Firstly we spent some time discussing how best to structure the source topics. Do we group them by product area? By topic type? Or some other arbitrary method?

We decided to group at the highest level (the top level folder) by user persona, and below that we grouped topics in accordance to how they are viewed from the product, so development kit wide ‘Events’ are stored in single folder, where as topics for a specific piece of functionality in the development kit are stored in their own folder. Your system will be different, of course, but this method suits our needs.

After that we need some way of knowing both what type of information a topic contains, as well as where that topic is used. We are not authoring in a DITA specific environment but decided to model our topic types on the DITA model to future proof us as much as possible (we are using Author-it which will export to DITA XML should we need it in the future). We have different templates for each type of topic (Concept, Procedure, Reference and so on), primarily to allow us to identify a topic (by default, Author-it shows which template a topic is using).

That leaves the final piece of our puzzle. How do know where a topic is used? This is more than just a list of which deliverables the topic will appear in, it also has to hint at the context of how the topic is being used.

Does any of this mean that we are more likely to reuse content? Not necessarily but it should give us a fighting chance, and once we’ve updated the content plans for all of our deliverables we will start to really see the benefits. Those content plans were the very things that suggested we could reuse content across multiple deliverables and I’m certain that, with a bit more analysis, we’ll get further gains.

Can single source and content reuse work? Of course it can. There are plenty of good examples out there and they all share one thing in common, something that isn’t really broadcast by the vendors; content reuse from a single source takes a lot of hard work.

But it is possible.

A quick reminder to those of you in the West of Scotland, there is an open meeting this evening to which you are invited. No agenda, just a chance to meet up with fellow technical writers. We are meeting at 7 p.m. in the offices of Sumerian in Glasgow city centre, at 19 Blythswood Square, Glasgow G2 4BG. Tea & coffee will be provided.

Thanks Katja for organising this, I’m looking forward to it as it’s always informative and interesting to meet fellow professionals. As my career progresses (or perhaps just because I’m getting older) I start to understand the true benefits of, what has now come to be known as, networking.

It’s the same reason I joined the ISTC, and also why this blog exists. I’ve been blogging, on a personal basis, for several years and have made some good friends so I have my own proof that blogging works as a way to network, to communicate.

It’s not that hard to quantify either. Directly because of this blog I realised how enthusiastic I am about my line of work, which made me want to get more involved which prompted the writing of a monthly column for the ISTC Newsletter and which also lead to my invitation to speak at the TICAD conference. I’ve swapped emails with technical writers from around the world and, quite genuinely, can say that through the blogs I follow I learn something new, if not every day, at least every week.

It can be hard to find the time to write posts, it can be hard to find something that I can write about (I try to steer clear of company specific issues), but it is rewarding and, I hope, of some use to others.

Networking isn’t easy. In a way I’m lucky as I have an outgoing personality, but the internet makes it so much easier. In saying that, it still doesn’t beat face to face communications so, if you are in the Glasgow area this evening, please come along.

How long is a piece of string?

It’s a common question and one I’ve occasionally used in reply when asked “We are building this new thing. How long will it take to provide some documentation for it?”

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. Although, to be frank, if you aren’t planning your work, you can probably stop reading now and go find a copy of Information Development: Managing Your Documentation Projects, Portfolio, and People.

So in the spirit of sharing, I thought I’d cover a planning aid I’ve used in the past and have, very recently, uncovered again. It’s focussed on topic based writing, so can be used whether you are single sourcing your content, or not but I should caveat that it was created with single sourcing your content in mind. This is based on a system I’ve seen elsewhere, alas I can’t recall the original source, if you know where this comes from, please let me know. I’ve adapted it for my own needs but happy to credit the original author (Hackos?).

The idea is simple enough. You break down your planned content into topics, with a topic defined as a discrete amount of information that shouldn’t take more than a couple of hours to write. Then, when you add in time for review and rewrite, you can take an educated guess at how long an ‘average topic’ takes to complete. So, for discussions sake, let’s say an average topic* takes around 5 hours to complete. Nothing revolutionary so far.

Each topic is then scored against four criteria, with the scoring used to add/subtract an appropriate level of variance:

1. Difficulty of Topic – do you know what you are writing about or is it brand new? Is it a simple topic or something complex?
2. Scope of Topic – Does the difficulty dictate that a lot of content is needed? Or is it a short topic of fixed content?
3. Availability of Information – are you updating an existing document? Do you have a specification to work from? Or are you having to write from scratch?
4. Access to SME – do you have good access to a Subject Matter Expert? Do you have limited access only? Or none at all?

Each topic is scored, from 1 (long, hard, complex) to 5 (short, easy, simple), against each criteria. An ‘average topic’ would score 3 for each criteria and won’t affect the estimate from the standard 5 hours. Scoring the topics this way allows you to factor in a level of variance, so a difficult topic with a large scope which has no information available and for which you have no access to an SME, will score lowest marks (all critera score 1) and has the highest level of variance from your standard topic estimate.

The criteria are fairly high level and you could certainly expand on these for a more granular approach but I’ve found that most issues can be assigned to one of the above criteria and that keeps the estimation as simple as possible.

The variance can then be calculated (again with an estimated time) so that you can adjust the time it takes to complete the topic, for example:

1. Score 1 – variance of +2hrs per criteria
2. Score 2 – variance of +1hr per criteria
3. Score 3 – zero variance
4. Score 4 – variance of -30mins per criteria
5. Score 5 – variance of -1hr per criteria

The figures given above are, also, estimated. You’ll note that the higher scored (and therefore lower variance) topics don’t ‘gain’ you proportionately the same amount as you lose to the lower scored (higher variance) topics. The reality is that, no matter how simple the topic, they still take time to create (increasing the gain numbers could result in a topic taking less than zero time to create!).

So a long, complex and hard topic, with little to no information and no available expert will will score 1 across the four criteria and so add 8 hours (2hrs per criteria) to the estimated completion time for that topic, taking the estimated total for that topic to 13 hours.

Flip the example round, a short, simple topic which comes with sufficient supporting information and an SME sitting on your desk to help you write it. That topic would score 5 for each criteria, and gain you 4 hours, meaning the estimated total for that topic would drop to 1 hour.

Now, the obvious thing to do would be to create a spreadsheet for all of this, that allows you to simple add in your topics, score them against the criteria and calculate the total estimated time (and whilst it’s at it, it can add in a level of contingency too). Which is exactly what I did.

Download the estimation spreadsheet (6KB ZIP file, contains Excel Spreadsheet)

The spreadsheet is annotated to help you understand it, and includes two additional columns which let us track when a topic was added to the spreadsheet (either as part of the initial planning, identified during the review cycle, or because of a change in product scope). All of the calculations are basic arithmetic so feel free to have a poke around and try this out.

It’s not an exact system, but that’s why they are called estimates and if nothing else it helps my team plan what they are writing about which, sometimes, is more valuable than the estimates themselves.

* this is probably the most contentious part of this method and may take some refinement to arrive at a workable number.

I try and follow as many technical writing blogs as I can but beyond the dedicated blogs there are other good sources of information and ideas out there. Finding these additional articles can be tricky as they can be found in a huge number of different sources.

To help with this Tom Johnson set up Writer River as a way to allow anyone (with an account) to post links to interesting blog posts and articles. The website has been running for a whlie now and continues to provide links to useful and topical articles.

I monitor an RSS feed of the website and whilst that is adequate it does mean that I can go a week or more without checking which can lead to a build of too many links to check. That usually means I skim the link titles rather than click through them all and the likelihood is that I’ve missed something that may have been useful.

So I’m delighted to hear that Writer River now has an auto-updating Twitter feed. Every link posted on Writer River will be pinged over to Twitter, and as I’m following Writer River on Twitter, I’ll see the links as they are added, increasing the chances of me taking a few minutes to click through to the linked website.

Time will tell but this is either a great use of social networking tools, allowing me to keep bang up to date and probably meaning I won’t skip any links, or another challenge to my time keeping, a quick check of Twitter during a context-switch* moment at work may lead to a longer break than I had intended?

We’ll see but, as ever, Tom continues to push his ideas forward to the benefit of us all.

Finally (this is an idea I had many moons ago) a one stop website which aims to list all technical communications (specific) tools.

In their own words:

One of the most common questions heard on many forums is “What tool do you use for [purpose]?” Answers vary, of course, because everyone has their own favorites and some folks will even answer that the right tool is “the one that best meets your needs”.

Sometimes, many people will answer that you need to look at the different tools, download trial versions, and test. But where is the list of tools to choose from?

It’s here at TechComm Toolbox, your online resource for all applications, services, and consultants related to technical communication.

I’d imagine there are still some applications to be added but why not go and have a look at the Toolbox. I’m sure it’ll come in handy in the future.

Note: I am not being paid to promote this website. The Tech Comm Toolbox was created by JTF Associates.