bookmark_borderWhat not to do

Working in a team that isn’t heavily invested in documenting requirements and specifications (we usually have a starting set of such things but these soon fall out of step as development evolves) makes it a challenge to know both what is being added to the product and whether it needs to be documented.

The development teams recently adopted JIRA and whilst the additional information helps I fear it may give us a bigger problem. As we will (should?) finally have a clear picture of everything being added to the product, will it be too much for us to handle?

At present the Publications team have two very large products, with a complex API and code base which is all evolving and which needs to be documented. We cover a mix of SDK style documentation, reference information as well as procedure based topics and many conceptual pieces. We don’t document all of the product at the moment but it’s fast becoming apparent that deciding what NOT to do will be a vital skill as we move forward.

We can’t, and shouldn’t, document everything but a firm focus on making sure we are providing the most value (bang per buck!) helps us make better decisions about what we can ignore, and what our customers really need.

How do you cope with the ever increasing pace of development? What don’t you do?

bookmark_borderDealing with change

It’s going to be a big year for us, both as a company and as a team. We have grand and achievable plans for the product which will mean the working processes for the Publications team will need to change for, as well as multiple streams of work with their own staggered release dates for the product, we are also restructuring our entire information set to improve ‘findability’.

Which immediately prompts a question, how do you improve ‘findability’?

The simple answer is would be ‘in as many ways as possible’ as there is no silver bullet. What may work for some, won’t work for others. However we have to start somewhere and the first thing we can do is restructure the architecture of our information, slimming down the content where possible with an eye to adding new formats of information.

We have already successfully piloted some new formats of information and will continue to roll more of those out for different areas of the product (in essence, these new documents are a high level overview of all the levels of an area of the product, from concept and usage to API implementation), and the signs are that the restructure will go a long way to meeting the needs of our customers.

Having been lucky enough to speak directly to some customers in the latter half of last year, I know that we are on the right path. The challenge will be to keep moving things forward amidst everything else. It’s going to be a busy year and already the analogy is one of a juggler who is keeping things in the air… for now!

bookmark_borderAlways learning

Next week the first of two new recruits joins our team. Both are graduates and whilst neither graduated from a Technical Writing based course they both have a good mix of skills, coming to the position through different routes. It’ll be a challenge for them, and a challenge for us, to integrate them to the team smoothly and successfully. I’m sure they will both do well, but to give them the best chance I’m preparing a few weeks of training for them, in various aspects of the job.

I’m trying to anticipate what they need to know, and when they need to know it, and whilst I’m very wary of letting my own experience get in the way it does mirror what they will be going through as my route into this profession was via an Electronic Engineering course, and I too had no experience in Technical Writing.

Training on our authoring tool (Author-it) is straightforward enough, and we will be mentoring each of the recruits as well so day to day questions we can handle.

We will likely use the IBM book “Developing Quality Technical Information” to provide a grounding in the basics of Technical Writing, along with an eLearning book titled Basics of Technical Writing that we purchased from CherryLeaf a few years ago.

They will have to learn how we do things, our specific processes, and learn how the overall Development team works so they understand where they fit, and they will receive a series of training exercises to complete before they take our product training course. On top of all that they will have a week long company Induction.

I’m a great believer in people learning by doing, so I’m planning a set of small tasks which will be checked and reviewed, and which will ultimately find their way into our documentation set.

Beyond that, I’ll be looking for them to ask questions, try things, make mistakes and learn from them, and then ask more questions. This industry is too varied to try and learn everything at once, and ultimately it’s down to them to decide what areas they want to push into… user experience? content design? API information? Who knows.

I do know it’s a challenge, for everyone involved, and that’s one of the things we, as a company, do best. There is a saying we have about being two feet outside your comfort zone, that’s where you learn best, that’s where you grow and start to understand your capabilities, so we will see how our recruits get on!

For me it’s doubly exciting as this is only the second time I’ve taken on graduates. I learned a lot the last time, both about how to train them and about my own foibles and attitudes to my profession so I’m brushing up my own knowledge to make sure I, and the rest of the team, give them the best change they have. In saying that, the first time I did this I was in my first ‘senior’ position, that was 10 years ago so hopefully by now I’ve gained a little bit more experience!

After all, you learn something new every day.

Have you brought a graduate into your team? Or are you involved in training or mentoring new recruits? If you have any suggestions I’d love to hear them.

bookmark_borderWhat do you write?

Most of my experience is based around software documentation. Whilst there are several levels to this, from task oriented User Guides through to highly technical API/SDK documentation, they tend to follow similar patterns making it easy for me to take my experience and apply it to new challenges.

I’ve also been involved in writing up procedures and guidelines as part of an ISO quality system, a little whitepaper style writing, and even the odd product brochure. All of which require a slightly different approach but the same grounding in the basics of understanding the audience.

However I’m aware that there are many other forms of technical writing, and I’m curious to find out what everyone else does? Do you write documentation for hardware products? Do you write proposals? Procedures?

Ultimately I’m starting to look at other areas of our profession to see if there are any good things that I can re-use where I am. If you have a moment, I’d love to hear what your main writing focus is, let me know in the comments.

bookmark_borderJack of all trades Pt. 2

My name is Gordon McLean, I am a Technical Communicator* and I am proud to be a jack of all trades.

I recall once being asked to breakdown all the skills required to be a Technical Writer, and then to provide a list of daily work tasks. The list of skills was to be used as part of a skills/training matrix, and the work tasks were to be mapped to a timesheet system.

At first I concentrated solely on the Technical Writers role, but even then you need to wear a number of hats; researcher, analyst, information architect, publisher, indexer, illustrator, proof-reader, editor… ohh and writer. All of those are unique job roles in some places yet, as a Technical Writer, you need to be able to successfully take on those roles to some degree. In most software companies a large part of the job is learning the new features, and as you have access to early builds, you are frequently also playing the part of ad-hoc tester. Admittedly you are usually only testing one scenario, and that scenario is the happy path that will be documented, but a bug is a bug and that means being able to identify one, discuss it with a tester or developer, or both, and why not log it as well?

If you are documenting an API or developer toolkit then, in those instances, you frequently don the cap of novice developer, asking the questions you expect them to ask, before switching caps to presume the role of an experienced developer and wondering if the information you are providing is too simple for them to use or if, perhaps, the structure of the information needs altered.

You need to be able to talk to developers and so you need to know a little about whichever code language they are working with, that way when they mention methods, you can ask whether they mean static or instance.

None of these skills/roles are the core part of a Technical Writers job, but simply additional strings to your bow. The more you know about everything, the more value you can add, so long as you don’t let that detract from your core responsibility, to provide documentation. However, the more you know about everything, the better that documentation will be and the higher your value will soar.

Prompted by The Top 5 Reasons to be a Jack of all Trades

* Communicator/Writer/Author, pick one. I favour ‘communicator’ because I don’t always communicate through writing, sometimes through UI design, sometimes through infographics and diagrams. You get the picture (pun intended!).