Over the years I've lost count of how many times I've had to say "I don't write that kind of documentation" when someone's asked if I can write something for them. I'm always polite about it, and I'm always willing to write it for them despite my lack of experience in that area, but nonetheless the overwhelming response is one of bemusement that I can't just magic up a document for them. I mean, it's just writing, and you're a writer, so why can't you, you know..... write it?
Now, I'm not talking about writing where domain knowledge is a problem. That can be an issue, but in a pinch if a developer can explain something to me and I can understand it I can write some documentation if I have to, even if I don't have the domain expertise I normally try to have. No, this is people asking me to write detailed SDK documentation for a product I've never seen in a language I've never been exposed to, or a configuration guide for a technology I've never worked with, or - my particular favourite - sales literature.
*deep breath*
Seriously. You don't hire a Ruby developer to normalise your database, or hire a mainframe guru to go heavy on JSON. And these people work in designed, limited languages. Technical writers operate in an unlimited, organic language in which meaning can be efficiently delivered in any number of ways. It might come as a surprise to the ignorant (of which, sadly, there are many in the tech industry) but writers specialise just like coders do. Yes, just like a good coder we can turn our hands to quite a few things, and we're pretty good in the areas around our specialisation, but an API writer is about as far from a marketing copy writer as a compiler programmer is from a mobile app developer.
With that in mind, here's a quick guide to some of the main types of technical writer:
API/SDK Writers
Not the same thing, because an API is not the same thing as an SDK, but the basic skills are the same: highly technical people, writing for other highly technical people and able to read, parse and write code. These writers are quite rare, because they need to be proficient in the language(s) you use whilst also being very good writers. This makes them valuable; expect to pay accordingly.
Technical Product Writers
Known as "Technical Writers" in the same way as End-User Product Writers (see below) but these writers focus on things like Installation, Configuration and Integration. If API writers are coders who can write, Tech Product Writers are IT engineers who can write. These writers have experience with enterprise systems like Active Directory, IIS/Apache, databases, and all that good structural jazz that applications use but end users never see or need to know much about.
End-User Product Writers
As above, these are just known as "Technical Writers" but rather than focusing on the people who install, configure and maintain the technical infrastructure, they focus on the people who'll actually use the application. This means writing for different targets, from newbie data entry interns to experienced SysAdmins. This is probably the "classic" technical writer that people picture when they hear the job title - writers of help files, user manuals, release notes, data dictionaries and so on.
End User Product Writers normally cover the biggest range and will often be the writers who cover "the rest", like knowledge base articles, FAQs, Support documentation, and anything else that is needed on the technical side of the product. Once you get further away from the product than this, you end up with....
Sales Engineering Writer
If the Sun is the product, Mercury and Venus are the API and SDK documentation, and the Earth and Mars are configuration/user guides, Sales Engineering Writing is Pluto. That is to say, it's right on the outer fringes of what can legitimately be called technical writing. But that's mainly because these writers work in Sales rather than Dev or Product Management or Support - i.e. places where technical people work - and so there's a certain amount of suspicion about their motives. But hey, I run a broad church here, so I'm including them. Sales Engineering Writers take technical concepts and put them into the simplest possible terms for Sales people to use in demos and tenders. In fairness, that's a tough job - have you ever tried to come up with an easily-understandable analogy for a self-balancing AVL tree? - because after a certain level of simplicity documentation changes from "really simplified" to "useless" and that's a fine line.
MarComm
Short for Marketing Communication. It's close, very close, or identical to a Copy Writer, depending on what company is hiring, but the essential difference is that Marketing Communication is often seen (rightly or wrongly) as being more marketing focused, especially in that social media way that everyone's pretending to love now at big companies, whereas copy writers are seen as more broadly spread over the sales and marketing gamut. Sadly we've already got as far out as Pluto, so I can't make a Uranus joke.
Copy Writer
A copy writer is someone who - duh - writes copy. Copy used to mean specifically journalistic writing, but over the years it now means relatively short pieces for public consumption, usually to get a specific message across. (Yes, the irony of saying that I'm not a copy writer as I write a short piece for public consumption to get a message across is not lost on me, but I'm not selling anything so it's not the same thing.) This means writing text that is designed to help pique interest in a product or service and aid sales. Copy writing and MarComm are firmly in the Sales and Marketing domain, and are about as technical as the salespeople they work with.
Following from this, there are quite a few domain areas that writers specialise in:
- Software
- Medical
- Finance
- Aerospace
- Rail
- Maritime
- Military (primarily because of the security clearance you need and the specialised writing standards they use)
These can all be broken down further, and I'm sure I've also missed some out (don't be afraid to enlighten me in the comments!), but it is further evidence that "a technical writer" is not a one-size-fits-all solution to your documentation needs. Each of these domains is specialised enough that they will be advertised as such - "Medical Writer", "Aerospace Writer", "Finance Writer", etc - in the same way that legal jobs are advertised - "Tax Lawyer", "Criminal Lawyer", "Contract Lawyer" etc. They might all come under the umbrella of "Technical Writer", but their knowledge, skills and experience are very varied. The only things they have in common are great English skills and an understanding of the principles of technical communication.
This article is by no means exhaustive, but at least you can wave it at the next person that thinks that a writer is a writer is a writer. And don't be afraid to ask them why they think technical writing is easy enough for people not to have specialities......
The Lone Technical Writer, aka Greta Boller, has just written an interesting article on why you shouldn't write everyday. She suggests that writing everyday can lead to burnout, a lack of joy and an inability to separate the good ideas from the bad ones, whilst stepping back can give you perspective on what you've written, a chance to learn more about your subject and the opportunity to remember why you love writing so much.
As a professional writer with a personal blog, my attitude is similar. I put a lot of thought and effort into the articles I write on Agile Documentation, and of the reasons that Greta gives for not writing everyday, the chance to learn more about the subjects I cover, is the prime reason I don't post more articles. However, some people feel torn between the horns of a dilemma when it comes to writing; on the one hand they feel they are unproductive or somehow failing if they don't write every day (or at least most days), but on the other hand writing everyday often has all of the drawbacks that Greta points out. I want to address some of the reasons for this and see if we can find a happy compromise.
To do this, let's look at why people feel bad if they don't write every day. I come from (the early days of) Generation X, the first generation for whom marriage, children, a steady career and retirement at 65 wasn't necessarily the best or most highly-regarded life choice. We in fact had many choices, and things in that area have only bloomed for the Generation Y and Millennials that have succeeded us as life's bright young things. The birth of the World Wide Web and the explosion of electronic and software engineering meant that we were the first generation to have mobile phones as essentially children - I got my first phone before I could vote - and the first generation of students who could research the vast majority of human knowledge at the click of a mouse. This has had many benefits, but one significant drawback is choice overload. We could see the breadth and depth of human knowledge stretched before us like a giant canvas, and so much of it looked interesting that it was, and is, hard to choose a single things to focus on for any long period of time.
This has got worse with the proliferation of interconnected digital media creation and storage devices. How many people want to take more photographs (and organise and curate the ones they've got on multiple devices and cloud storage accounts), find new music (and organise and curate the music they've got on multiple devices and cloud storage accounts), read more books (and organise and curate the ones they've got on multiple devices and cloud storage accounts) and watch more films, TV shows and documentaries (and organise and curate the ones they've got on multiple devices and cloud storage accounts)? People have a voracious appetite for both learning and expressing themselves, and with so many things to explore, and so many things to get good at, how do you choose? Whether it takes 10,000 hours to become an expert at something or 10 hours, there are still only so many hours in the day, and a finite amount of days in your life. It is no longer possible to be a renaissance man and know everything that man knows, like Da Vinci. And on top of that, if you want to express yourself and create something, that takes time to master as well. No-one picks up a piece of marble and a hammer and produces a Michaelangelo first time round, and no-one can write War and Peace from a standing start.
With this whirlwind of choices in mind, there are things like NaNoWriMo, National Novel Writing Month, where you write a certain number of words each day and at the end you have, if not something publishable, a serious chunk towards a publishable work. There are similar challenges with photography, film watching, novel reading, crafting, programming, language learning, and a whole host of other creative or learning pursuits. These challenges are geared as much as anything to people who want to be personally productive and make efficient use of their time to learn, understand and create as much as they can in the relatively short life span of a human. There are also MOOCs which can have tens of thousands of students, and these are incredibly popular, because the drive for learning seems to be universal. This drive for learning and achieving can create pressure and lead to a feeling of failure if you're not hyper-productive all the time. Basically, people want to be Tony Stark, or Elon Musk, or [pick your unbelievably productive hero here]. I won't go into the psychology of this - because it's presumably quite complex and highly contextual, and I'm not a psychologist - but I'm aware that it exists, and I'm aware that a lot of people suffer from this combination of intense drive and choice overload, which can often lead to feelings of failure. If you've read this far you're probably aware of it too.
Which brings us to writing every day. If you're struggling to write every day then NaNoWriMo won't change that. It might change it for a month, but when a family member gets ill, or you've got a ton of housework to do, or 8 weddings, a funeral, 3 christenings and 5 birthday celebrations to attend in the space of 4 months, the fact that you spent an hour a day for 30 days working on a novel back in November isn't going to help you. Life gets in the way. That's normal. Besides, at the end of that 4 month period you'll have a lot more to write about, simply because you haven't written much. I'm not knocking challenges like NaNoWriMo at all, because they're a great way of working on your self-discipline and churning out a lot of work, but that doesn't mean that you have to work like that every day of your life to be productive. Ah, but, I hear you say, the best way to Get Things Done is to make them a habit and do them for at least 10 minutes a day so that you can make progress! Yes, and if you're keeping on top of your email or rebuilding an engine that productivity and project management approach is very effective, but writing is not about being efficient or getting better. Allow me to expand on that.
There's an old saying that goes something like "If you want your child to become great at a sport, give them one ball", the idea being that you can be good at football and rugby and cricket, but you can only be great at one of them, and to that you need to specialise. Therefore, if your child spends time playing rugby, and only rugby, they'll have a chance to be a great rugby player because they'll get better and better the more they play rugby. As with rugby, the theory goes for some people, so with writing: Dedicate yourself to writing and you could be great at it. But are you REALLY writing in order to get better at writing? Or are you writing to express yourself, to have a creative outlet, to give yourself a sense of satisfaction, fulfilment and achievement? Becoming a better writer takes training, learning and effort. That doesn't mean writing everyday, it means practising writing regularly and with a purpose. That is not the same thing as writing a blog post or another chapter in your novel.
I doubt many people who blog or write books do it in order to get better at writing, except occasionally as a technical exercise for reasons of professional or academic advancement. Besides, the quality of practise is more important then quantity, so writing everyday might build discipline (which is good), but it won't automatically make you a better writer. The wheels will spin, but you won't necessarily be going anywhere.
You can apply the same logic to most creative pursuits such as music, photography, film-making, and so on. Doing nothing but taking photos might help you develop a rule of thumb for the types of photo you take, but it won't teach you the principles of effective composition that can be used in every situation. For that you need to learn about the theory and how to apply it. Otherwise you'll keep taking 1000 photos a day and getting 2 or 3 good ones, mainly by luck, whereas with a little theory you can take 500 a day and get 5 or 6 good ones, partly by understanding what makes a good photo. Writing is the same. Writing 50 pages a day of which you keep 2 is a worse use of your time than writing 10 pages of which you keep 9.
So, if I'm suggesting that writing every day isn't that worthwhile, how do you build the habit of writing and do it regularly? Well, as this is a blog about writing in agile environments, you will not be shocked to hear that an agile approach can help. Instead of focusing on how often you'll write, focus on what you'll produce instead. As an example, let's look at this blog. I know that, all things being equal, I can write 4 articles a month. So that's my velocity and sprint size right there - 4 articles a month. The obvious way to look at this would be to say, ok, why not 1 a week then? And the answer is equally obvious: Life gets in the way. If I'm having a busy week, or I'm ill, or work has gone crazy, I don't want this blog to suffer, but it can't be a higher priority than my work or my family, because I work to provide for my family and the blog is a personal project. So whilst the priority of this blog is higher on my personal backlog than, say, watching a new box set, it's not higher than paid work or my family. And work and families being what they are, the chances of a week going by without me having adequate time to write an article I'm happy with are relatively high.
But I also get weeks where everything is quiet, and that when happens I double down on the blog writing. The important boundary is that I've got one month to produce 4 articles. My month is a black box, and the customers - that's you, dear reader - don't care how I get the articles done within that month, you just care that they are done, and that the blog is regularly updated.
There are other benefits to an agile approach as well. I've got a minimum marketable subset of 3 articles a month. Less than 3 and the blog isn't updated enough for my liking, so I always do a minimum of 3 (unless circumstances are very unusual, in which case life comes first), but 4 is my goal. A month also allows me periods of time when I can accept that my writing mojo isn't high. If I had to write an article every week I'd have an opportunity to fail every 7 days, and sometimes my brain just doesn't work to that schedule so I'd be setting myself up for failure. But I love writing and I know that my mojo will come back, so I know I can achieve at least 3 articles a month almost every month with a relatively small amount of effort (because I love writing, so it's not a huge effort to write when my mojo is present and correct). A month is long enough for me to look back at my past articles and have some temporal distance to be honest with myself about what's worked and what hasn't and do a kind of personal retrospective. It also gives me enough time to discover interesting articles (like Greta's article that made me think about this) and do a bit of planning and grooming of future articles.
(The irony is that for the first time I've just missed my target. I've only posted 1 article in October 2015 because it's been the busiest month I've had for several years, but I still wrote 3 articles, including this one. It's just that I planned to post 2 articles on 31st October, but circumstances intervened and I'm posting them on 1st November instead. Despite this minor hiccup I still wrote the articles in October, which gives me confidence that the system can work even in the busiest months.)
I won't stretch the agile analogy too far, but the general concept of a sensible, repeating time period with a realistic goal at the end of it has worked very well for me, and I've started to apply variations of it to other things I want to work on. You can add goals to your monthly sprint, like "take photos of 3 sporting events", "bake 5 different cakes", "read one book", or whatever you want. Just make sure that the things in your sprint aren't the day-to-day of email management, budgeting, cleaning, or anything else that you can use a to-do list for.
Having tried the "build a habit by doing it everyday" approach, I can honestly say that an agile approach has made me much more productive and, crucially, stopped me burning out whilst still allowing me to build a habit. And if I want to write every day I can. I just don't have to. Like many people I want to read, learn, understand, create, experience and achieve many things and agile has so far proven to be the best tool to help me get there. Go on, give it a try. You might be surprised.
The idea of working for one company from youth to retirement has become almost quaint, especially in the tech industry. For many people the only way to get a decent pay rise, or work on new things, or to move up the career ladder, is to move to a different job. And with globalisation following the low costs areas around the world as various currencies and tax regimes and legal situations fluctuate and evolve, even if you don't leave voluntarily there's a good chance at some point you'll leave involuntarily. To all intents and purposes, it is a certainty that if you've got more than 10 - 15 years before you can retire, you're going to move jobs. And moving jobs is a scary prospect, because change is often difficult and interviewing is scary and moving to a new company can be daunting.
I know, what a joyful opening, eh? But it's not all doom and gloom, because changing jobs is also refreshing, eye-opening and challenging, and you can get that pay rise or chance to work on new things or promotion that you want. So let's focus on the positives and assume that you've decided to take the plunge and look for a new job to make your life more satisfying. You can take or leave the job you're interviewing for. How can you find out whether the company you're interviewing with is right for you?
Let's get one thing clear: If what you want is money, and you're interviewing for a company that will pay double what any other company pays for equivalent roles, this article isn't for you. Take the job and spend the crap out of your new salary! (Also, do your brethren a solid and tell us who the company is and if they're hiring.) That's not to say that you shouldn't just check to make sure that the company isn't run by lizard people who are plotting to exterminate the human race - that'd probably stain the ol' resume when you move on - but generally speaking, if you want a honking great salary and can deal with the working conditions, just say yes, sign on the line and crack on.
Unfortunately, that kind of high-paying gig doesn't crop up often and anyway, people have needs that go above and beyond money. Sure, you need to pay your bills each month, but once you're earning a salary that enables you to do that then you've got to look at the other factors that make you happy. What are these factors? Let's hit the go-to diagram for amateur psychologists everywhere to find out:
This is Maslow's Hierarchy of Needs, the much quoted, copied and discussed framework for understanding human motivation. We're not looking at the most basic motivations - the Physiological and Safety levels at the bottom of the pyramid - because if you need to change jobs to find food, shelter or safety then just take whatever you can. Rather, we're focusing on the top 3 levels: Love/Belonging, Esteem and Self-actualisation. To help us understand what they mean, here's an expanded version of the diagram:
For the purposes of finding a place that you actively want to work in, you need to understand what it is that you need and enjoy the most. That way you can ask the right kind of questions at interview to find out what the company attitude is in areas that are most important to you. Let's breakdown the 3 levels to see how they apply to your working environment.
Love/Belonging - This is about belonging to a tribe, being part of a group. For some people this is particularly important, for others it's not. If you're the kind of person who needs a sense of togetherness and community in your work place to be happy, then this is important to you. If you wonder how anyone could want to work somewhere without this, remember that it's not a binary choice. You can work for a company where you get on with your colleagues without wanting or needing close relationships; this doesn't mean you dislike the people you work with, it just means it's not that important to you whether you build close bonds or not.
Esteem - This is about doing a good job, being recognised for it, and recognising it in others. It's often the difference between doing a job that is seen as a necessary evil and doing a job that is seen as a positive benefit. Nobody wants to do a job for which their co-workers have disdain or contempt. The only thing worse than this is doing a job and feeling contempt for yourself for doing it. It's ok to want an occasional comment of appreciation, and it's ok to want other people to think that you do a good job of something that benefits the company. It doesn't matter if you're a cleaner (a job which is very under-appreciated - imagine how grim the bathrooms and kitchens in your office would be if no-one cleaned them for even a week) or a captain of industry, everyone likes to feel appreciated at least a bit.
Self-actualisation - This is about the fulfilment of potential and the need to achieve great (to you) things. It's common for this to be expressed in terms of wishing one could write a novel, or climb Everest, or go to the moon, but the intrinsic desire is more generic: to achieve something that is both rare and difficult, to have mastery of oneself and one's environment, to experience things which expand the boundaries of your world in a fundamental way. In the context of work this might be becoming a well-known guru in a particularly complex field, or building up your own successful company that disrupts the established order, or it could be something as simple as being the best you can be at what you do.
Don't think of these as stages through which you should progress, with each one representing more "success" than the previous stage. It's entirely possible for Person A to feel self-actualised by achieving things and living in a way which wouldn't satisfy Person B. Likewise Person A might think that Person B's desire to climb Everest seems unpleasant at best and their idea of hell at worst. It's all personal and all relative, especially as you can want or need any and all combinations of things from all 3 stages to be happy. Think of the stages as compartments on a serving tray, where you can pick what you want from any compartment.
With that in mind, here are some example questions which you can use to start finding out about your potential employer's attitude to what's important to you:
Love/Belonging:
- Does the company see people skills as more or less important than technical skills?
- Do you encourage cross-disciplinary working?
- Do the writers sit and work with the rest of the development staff?
- Are there flourishing clubs or activities, like a cycling club or poker school, where staff can spend time bonding?
Esteem:
- Does the company see documentation more as a necessary cost, or more as a value multiplier?
- Does the company operate a peer-review process for their documentation?
- Where do writers fit into your strategic plans for growth and success?
Self-actualisation:
- What is the yearly training budget, and how much time is allocated for training?
- Are there opportunities to move to different projects based on my interests and prior learning?
- Are your staff given autonomy and support or are they closely managed and monitored?
- Do you have a mentoring and/or coaching program for staff?
Of course there are many such questions, and these are only examples. They're also weighted towards documentation roles, so if that's not your area the Esteem questions in particular won't be much use to you. But in general terms, if you can work out what it is that you like and dislike about your current role, you'll be much better prepared to find out what your new company can offer to make your working life happier and more fulfilled.
