So, 2015 has come and will be gone in a few hours (or already has gone if you're in Australia). Happy New Year to all my readers! I hope you have a great 2016. As a present to see in the New Year, here are some links that you might find interesting if you're a documentation person. Happy reading :-)
- 6 writing tips from the master, George Orwell
- DITA. Try it, you might like it.
- A quick start DITA YouTube tutorial
- A decent Tech Writing course that's free? You're welcome.
- A great SlideShare intro to API documentation from the maven Sarah Maddox
- Ignorance is Strength. Yes, you can improve your company's documentation, even if you're a peon with no power, influence or authority. Watch the video. Learn. Do.
- An old favourite. Learn HTML, CSS, XML, and a bunch of other stuff, for free, in a simple, well-designed, effective site.
And finally, a few lesser-known Word features for those of you who still love the old girl:
N.B. Apropos of nothing, this is also the 50th post here on Agile Documentation. That's gone quick. When I started the blog back in February after about a year of procrastinating, I hoped I'd have the self-discipline to keep it going for a few months. I didn't expect that 10 months later I'd be constantly thinking about blog articles, with 50 articles published and another 50 or so in my backlog. My free time is tight but (family aside, obviously) Agile Documentation has become a priority and I really enjoy writing it. Thanks to everyone that's taken the time to read an article, and especially to those who've posted a comment - I really appreciate every one of you.
When building documentation management systems (DMS) there is a temptation to put all of the content into a hierarchy of one kind or another. This isn't always a mistake, but it shouldn't be the default structure. In fact, I'd go so far as to suggest that it should only be used when there are compelling reasons to do so (and "I'm the most important person and I want a hierarchy" is not compelling).
A note for those who might not have a DMS in place yet, or those who want to learn more about them: A DMS is more properly called an EDMS, or Electronic Documentation Management System, but the "E" is often left off due to the assumption that people are talking about the management of documents on computer systems. A non-electronic DMS would nowadays probably be akin to archival work. DMS is not carried out using a normal file system like Windows Explorer (at least, not by professionals), but rather on specialised software tools that have functionality like version control, check in/check out and permissions. Examples would be Documentum and SharePoint, but there are many others.
So, if not a hierarchy then the obvious question becomes: What structure should be used instead?
The obvious answer is: A tagged heap.
By a tagged heap, I mean a heap, a pile, a bucket, a single folder/list/library that contains all of your documents, with each document tagged, labelled, indexed, categorised or having otherwise had metadata applied. Retrieval becomes a matter of searching, filtering and ordering rather than navigating, drilling down and visually scanning. In most cases it's quicker for users and easier for administrators to maintain in the long term.
This is a big claim, especially if you've never been exposed to the power of searching a tagged heap. Also, hierarchies are popular, and the power of control they offer is a hard thing to give up, so I might have some convincing to do. Let's start that by looking at the pros and cons of hierarchies:
Pros of folder hierarchy
- Already understood and used by computer users - low to none learning curve for functionality;
- Easy to permission a folder (and by extension all of the files inside it);
- Low cost of setup;
- High level of control for administrators.
Cons of folder hierarchy:
- Content can only be stored in one folder (and by extension one place in the hierarchy);
- High learning curve for large or complex hierarchies;
- Only someone who knows the whole hierarchy can move through it efficiently or quickly;
- High cost of moving content in the event of a change of hierarchy (e.g. due to organisational change);
- "Logical" for the hierarchy creator will not be the same as "logical" for a lot of the users;
- Very inflexible;
- No standardised metadata between different file types (or versions, such as .doc and .docx);
- Searching is difficult if you don't already know the name and location, leading to user frustration.
- Slow to click through folders, read the next list of folders, click the next folder, etc, etc.
What can we take from this? Well, folder hierarchies might be familiar and easy to use, but they're inefficient, inflexible and illogical for a lot of users. Familiarity and ease of use are all well and good, but there is a significant life-long cost to that which is hard to justify. The two costs that stick out immediately are the high cost of administration AND the high cost of using. Isn't that actually a worse case scenario? That's only 1 step above not having a DMS at all.
Still, familiarity breeds both comfort and contempt, and maybe I've gone too far towards the latter. After all, there's a reason folder hierarchies are so popular and ubiquitous, and it can't be because people actively like things that are rubbish (no X Factor jokes, thank you very much). So people must value the control a hierarchy gives them and the low cost of setting up and permissioning folders, because those are the big benefits, right? Or, is it because there is no obvious alternative? Or that people can't see the benefits of an alternative?
A tagged heap is a strong alternative, and has a lot of benefits. Let's look at the pros and cons.
Pros of tagged heaps
- Content can be viewed based on any number of searches, orders and filters, so location doesn't matter;
- No learning curve as search is as ubiquitous as folders;
- A system novice can find something as quickly as a system expert;
- No cost of hierarchy change;
- No logic gap between creator and user;
- Infinitely flexible, as views can be created in any way the system allows;
- Standardised metadata across all file types (using things like mandatory columns, labels, etc);
- Searching is easy because of the metadata (such as date of creation, author, file type, description, etc)
- Extremely fast file retrieval (modern search algorithms can search and return results from tens of thousands of records in less time than it takes to blink your eye).
Cons of tagged heaps:
- Higher learning curve for users who are adding documents, especially for adding metadata;
- Permissions can require more design;
- Higher initial setup cost;
Unlike a folder hierarchy, the more a user puts in the more they get out. This specifically applies to metadata, but on the basis that, as every administrator of every system ever built knows, not every user is as diligent as they should be, any modern DMS system can be setup to make metadata entry mandatory. The more metadata is entered, the more powerful the views and searches will become. This does require an intelligent, thoughtful approach to metadata design though, hence the higher initial cost of a tagged heap system.
My argument would be that ease of setup and ongoing administration is not as important as ease of use for the people who'll be using the system on a daily basis. A balance does need to be struck, because a system that's incredible for the 50 people who use it, but for which 50 administrators are needed, isn't a sensible purchase, but in general the users of the system are the ones who'll determine its success (or not). We've all worked in places where a decision has been made to implement a system that the directors and/or administrators love, but which is execrable for the users. And what happens? People use it as little as they can get away with, thus removing a lot of the intended benefit. There's no point implementing a system that has such a poor ROI.
Although using a tagged heap does have a higher initial cost, the benefits for the users are legion and compelling. On that basis, I'd use a tagged heap and consign complicated hierarchies to the recycle bin by default.
If you've got experiences that confirm or contradict the benefits and ROI of a tagged heap, drop a comment in below and let everyone know which you prefer.
The morning after A Note on Latin Phrases was posted, an article dropped into my feed reader with the serendipitous timing that normally occurs when you find your lost wallet just as you finish cancelling the final credit card it contained. McWhorter's erudite and deeply engrossing homily to the mongrel that is the English language conjures an image of a hotch-potch of invaders, nouveaux speakers and gnarled locals mangling the mother tongue time and again until it loses a single family resemblance and becomes a child of most of Northern Europe.
The overlay of one language on another, with the resultant twisting and changing and joining of the vocabulary and grammar, is followed by the overlaying of another, and another, intertwined with pockets of native resistance and other languages that become, briefly or otherwise, bedfellows with our increasingly individual and unrecognisable language. This commingling and inbreeding leads to English's - apparently well-deserved - reputation for illogic and difficulty of mastery.
But aside from being a fine read (and I whole-heartedly recommend reading it) McWhorter has provided a mine of interesting gems about the effect of Latin on the English language, hence the poor timing for me. I would have gladly folded in some quotes, but, alas, I clicked Publish too soon. You'll just have to read the article yourselves, but here are a few points of interest:
"[S]tarting in the 16th century, educated Anglophones developed a sense of English as a vehicle of sophisticated writing, and so it became fashionable to cherry-pick words from Latin to lend the language a more elevated tone."
"One result was triplets allowing us to express ideas with varying degrees of formality. Help is English, aid is French, assist is Latin. Or, kingly is English, royal is French, regal is Latin – note how one imagines posture improving with each level: kingly sounds almost mocking, regal is straight-backed like a throne, royal is somewhere in the middle, a worthy but fallible monarch."
"Nevertheless, the Latinate invasion did leave genuine peculiarities in our language. For instance, it was here that the idea that ‘big words’ are more sophisticated got started. .... The English notion that big words are fancier is due to the fact that French and especially Latin words tend to be longer than Old English ones – end versus conclusion, walk versus ambulate."
So, if you want to know why there is an air of the common man about exhortations to "Never use a long word where a short word will do", it's because longer words are associated with Latin, the language for a long time of the only educated man in the village: the priest. Shorter words are, quite literally, more Anglo-Saxon, and associated as such with the less educated. If you want to be understood by the widest possible audience, you use the most commonly understood language, and that is not Latin.
(In light of this and the previous post on Latin phrases, comments on the irony of my gratuitous over-use of adjectives and long sentences on this blog are more than welcome.)
There's a tendency among some writers to think that sprinkling a little Latin - or worse, Greek - in their writing makes them look like a learned scholar.
It doesn't.
Instead, it indicates either a lack of confidence (hence the need to bolster the text with Latin to prove your erudition to yourself) or gross over-confidence (hence the need to bolster the text with Latin to prove your erudition to others). Either way, Latin is not the right tool to prove yourself.
Reasoned argument, written in clear, concise English will always win out against stylistic flourishings that do more to highlight your self-esteem issues than your argument. Writing is a demonstration of the clarity of your thinking; adding phrases from dead languages merely muddies that clarity in unflattering ways.
That being the case, there are of course exceptions where Latin expresses a concept far more concisely or commonly than the equivalent English. If these expressions are in regular use, you may use them. Otherwise you may not. Acceptable Latin phrases in general communication are:
- ad infinitum (if for no other reason than the equivalent "to infinity" will now inevitably be suffixed in the reader's mind by "and beyond!", which is probably not what you intended your writing to inspire)
- ad nauseam
- annus horribilis (but only ever for a British audience, as it is famous in these isles but not necessarily elsewhere)
- a.d., a.m., b.c., p.m. (but never expanded)
- bona fide (but bona fides should be left for small time American hoodlums)
- carpe diem
- caveat emptor
- deus ex machina
- emeritus
- et tu, Brute?
- etc (but only rarely et cetera for emphasis)
- e.g. (but never exempli gratia)
- in extremis
- in flagrante delicto (but only when discussing the nocturnal activities of those who should know better)
- in loco parentis
- in memoriam (but only in formal writing such as an engraving or death notice)
- in situ
- i.e. (but never id est)
- lorem ipsum (although this is almost a proper noun nowadays, and yes, it is Latin despite the widespread belief that it's gibberish)
- magnum opus (but only where what you are referring to is truly such)
- momento mori
- modus operandi (M.O. is also acceptable)
- non sequitar
- N.B. (but never nota bene)
- per se
- persona non grata
- post coital
- P.S. (but never post scriptum)
- quid pro quo
- Q.E.D. (quod erat demonstrandum should not be used unless making a specific point in an academic or scholarly article)
- sic
- sine qua non (but only if you must, and only if you wish to risk pretension)
- terra firma
- vice versa
These may be used in general writing; in technical writing you may only ever use a Latin phrase where not only is that phrase lacking an English equivalent, but also where the phrase is common enough that it is considered to be vernacular. 156 A.D is a good example where the equivalent - "in the year of our Lord 156" - is so anachronistic as to be less understandable than the Latin. The only time that Latin is otherwise acceptable is when your work is for the Catholic Church and only for the Catholic Church, in which case the more Latin you use the cheaper your translation costs will be.
If there is an equivalent English phrase that is just as concise, use that. Inter alia means "amongst other things" or "in amongst". Both of these are as clear as inter alia and are preferred. Similarly, exempli gratia can be replaced with "for example", whereas e.g. has the advantage of both concision and common usage. Sui generis translates as "in a class of its own" or "stands apart on merit" and either could be used instead. Tabula rasa can be replaced with "blank slate" unless actually discussing Enlightenment philosophy.
Re is a curious case where thanks to email parlance it has come to be seen simply as an abbreviation of "regarding". As such its use in the formal sense is almost entirely unknown and therefore should be avoided in any context that is not purely communicative. Similarly, semper fi(delis) has been used so much in TV and films (thank you, NCIS) that it should be considered as reserved for United States Marine Corp personnel only.
In technical fields you can use as many Latin phrases as are proper - cogito ergo sum, habeas corpus, in utero, primus inter pares, vox populi, etc - but again only where an equivalent English phrase does not exist, or where it does exist but does not carry the same weight of bundled meaning (the cogito being an exemplar of this). Do not use words from within these phrases out of context; there is no need to use ergo when "therefore" will suffice.
There are also many words which are so ingrained in our language that most people wouldn't take them as Latin words - agenda, circa, post mortem, versus. These may be used freely, as may titles of literary works such as Dulce et decorum est. Excelsior! may also be used, but only ironically. Proper nouns, such as Opus Dei should be treated as any other proper noun.
Any other Latin phrase (sic transit gloria mundi, vini, vidi, vici, etc, etc) should be avoided on the grounds that the majority won't understand it, and the English equivalent is perfectly acceptable. And again, for clarity: No Latin phrases in technical documentation, except a.d., a.m., b.c. and p.m.!
I had an interesting conversation recently regarding the order of sprint meetings, and whether it mattered what order the review and retrospective took place. This lead to a wider conversation about whether you could do review, retrospective and planning in only 1 or possibly 2 meetings. That all sounded a bit "dirty agile" to me, which is normally a good cue to re-examine my assumptions to see if I've been thinking too rigidly.
In my head, the sprint ceremony order is one of the inviolable "rules" of scrum, so much so that it didn't really occur to me that people might think differently. It's just one of the default assumptions I have about how scrum is done, rather than a subject for debate. After discussing the matter I still don't think this is something about which you can be flexible, although this is not stubbornness so much as the lack of a compelling argument to the contrary. I'm open to persuasion if such an argument exists though.
The agile mantra of "Inspect and adapt" is high on my list of principles, so to that end I'll lay out the order of sprint meetings and why they need to be discrete meetings, and if anyone wants to chip in with counter suggestions I'm all ears.
First, the facts as I see them:
- The Review should happen on the last day of the sprint.
- The Retrospective should happen on the last day of the sprint.
- The Retrospective should take place after the Review.
- There should be a break between the Review and Retrospective of at least an hour.
- The Planning should happen on the first day of the next sprint.
- The Planning for the next sprint should never happen until the Review and Retrospective from the previous sprint have been completed.
And now the justification for each of those points:
1. The Review can only happen once all of the sprint stories have been completed and not before. Therefore the Review needs to happen at the end of the sprint. If all of the stories in the sprint have been completed before the end of the sprint then either additional stories can be added - if there's adequate time to complete them before the end of the sprint - or the team can groom the backlog, triage support requests, refactor code, and any other tasks that don't impact the sprint velocity. (If a task impacted the sprint velocity it would be story-pointed and as such be a story that was added to the sprint.)
The Review will already be a recurring appointment in the stakeholders' calendars and as stakeholders are often in demand it shouldn't be assumed that bringing the Review forward will be simple case of sending out an updated appointment. This is especially true where stakeholders are many and/or senior. But this a practical objection, albeit a sensible one, and as such doesn't have the force of compulsion. The compulsion should lie in the fact that moving the review forward serves no purpose. Assume that the Review is moved forward. Either the Retrospective is moved forward as well or it is not. If the Retrospective is not moved forward then moving the Review has served no purpose because the team still has to wait for the Retrospective. If the Retrospective is moved forwards as well then the end of the sprint must be moved forward, otherwise the team will have to wait for that instead. If the end of the sprint is moved then the next sprint must be started. This means that your sprint will start on a sub-optimal day. Any teams working on the same sprint cycle will now be on a different sprint cycle. The team's velocity calculations will no longer be valid. Your customers - assuming you release an increment at the end of each sprint - will have to change their processes to accommodate a different cycle. There are other issues that will arise depending on circumstances, but all of them revolve around disturbing the cadence and rhythm of the sprint cycle. Scrum is predicated on having this cycle as part of the methodology for successful teams; there appears to be no benefit to disturbing it.
2. Assuming that the arguments for the timing of the Review ceremony hold, the same will apply to the Retrospective. Therefore let's look at the order of the Review and Retrospective meetings.
3. There is an argument that holding the Retrospective before the Review allows the team to deal with what went wrong and then finish the sprint on a good note with the Review where they can show off their work to the stakeholders. I like the sentiment, but not the logic. The argument hinges on 2 unfounded assumptions, namely that the Retrospective is all about what went wrong and therefore is a necessarily less than enjoyable meeting, and that the Review will always go well. Neither of these assumptions stand up to scrutiny, regardless of personal experience. That's not to say that for some people Retrospectives are a generally unpleasant experience, nor to suggest that every team has had a Review that didn't go well. But my assertion is firstly that a Retrospective should neither focus purely on what went wrong, nor be an unpleasant experience, and secondly that the assumption of future Review success based on past glories is hubris that will inevitably bite the team at some point in the future.
The long and the short of it is that the Retrospective should be honest but not unpleasant. It's true that if you are the kind of person who doesn't take criticism well then you might not like hearing that something you were responsible for didn't go well, but frankly that's your problem and you owe your team a more mature attitude. Likewise, if there is a team member who revels in shoving failure down the throats of their team-mates that's not pleasant either, but the group should combine to shut that person down (or in extremis remove them from the team). Being part of a scrum team means learning and growing through an iterative process. You have to be open to that.
Likewise, Reviews can go wrong. More importantly, they can teach you things you didn't know if you have active stakeholder participation (which you should have!). Either way, the Retrospective is where these things should be discussed and actions created. This can only happen if the Retrospective happens after the Review.
4. Ok, fine, we do the Review then the Retrospective. We'll do them in one meeting and get it all out of the way, ok? No, not ok. The Retrospective should be a separate meeting, because what comes out of the Review needs to be thought about before having the Retrospective. Also, people work better when they've had a break, and the Review can be tiring if you've got a lot of questions to answer from stakeholders. Give people a break for an hour or two, let the Review comments sink in, then do the Retrospective. You'll all get more out of it that way
5 If points 1 - 3 are assumed, then the timing of the Planning meeting becomes self-evident. You can't complete any stories unless you've got stories to work on, and to get your stories you need to have a Planning meeting.
6 Well, why can't we plan our next sprint if we've got some spare time? Because actions will come out of the Retrospective, and quite possibly the Review, and these should be captured in your task management system and might need to go into the next sprint. You can groom items on the backlog, and that includes estimating story points and task time, but you won't know what the final priorities are until all of the previous sprint has been completed and the Product Owner has updated the backlog with the latest priorities.
Hopefully that explanation provides solid reasoning for you, but don't be afraid to drop a comment below if you disagree!
There is a fair amount of disdain amongst some writers for using Microsoft Word to produce documentation of any size. I use the word "disdain" because the people that "hate" Word normally type "Micro$oft" as a mark of how edgily anti-establishment they are (while using an iPhone). There's no point engaging with these people in any meaningful way, because they're either teenagers trying to look cool (because all the ladies love a man who knows bash, right?) or adults who have a lot of unresolved issues (seriously, why don't women understand how cool I am???).
Very few writers actively hate Word, and when we do, it's oddly got nothing to do with whether Word is actually any good. As it happens, even writers who use variants of SGML every single day and never go near Word will acknowledge that if you just want to whip up a one page letter then Word is the tool to use. However, that doesn't mean they'll use it to whip up a one page letter, because they're professionals.
And there it is. That, dear reader, is the problem that a lot of writers have with Word. It's snobbery. But before you get all hot under the keyboard and splutter indignantly in the comments, I need to contextualise that snobbery a bit.
Word is an astonishingly polished and powerful writing tool. I've been at this professional writing malarkey for over a decade, and in that time I've used Google Docs, Open Office, Libre, Zoho and a few others I can't even remember and none of them come even vaguely close to matching Word's functionality, intelligence and integration points. This is especially true for Office 2013 and the desktop version of 365. No matter how one-eyed you are about Word and it's faults - and it does have faults - if you deny that Word is the single most capable word processing tool around then you're wrong. Fact. It's not even a matter of opinion. It's not like arguing about whether the Aston Martin DB9 or Jaguar F-type is the prettier car where there is room for subjective opinion, it's about plain facts. Word can do more, do it better, and do it more intelligently than anything else out there.
So why the snobbery? Why don't some writing professionals give Word the love it deserves? They don't use it everyday, because there are better tools for things like single sourcing, topic based authoring and so on and so on and that's fair enough. Word is designed to allow you to write everything from a 1 page shopping list to a 500 page book, and it will do those and everything in between very well, but it's like buying a Range Rover. You can drive over almost any terrain in a Range Rover, and do very illegal speeds on the motorway, and be very comfortable, and fit a lot in the boot, but it's not as good as a tank off-road, or a Ferrari for high speed or a Rolls-Royce for comfort or a van for load capacity. But it's still the best all-rounder by some distance. That's Word. Other writing tools offer specialist functionality, but is there a single PC user who hasn't used Word to write something at some point? Unlikely. And if there are, their numbers will be vanishingly small, because Word is just the best all-round package available and therefore the most ubiquitous. (There are additional reasons to explain the Office hegemony, but that doesn't change the facts about Word's pre-eminence.)
If you want to understand the snobbery about Word, it can be boiled down to that pre-eminence. It's not the fact that Word is popular, otherwise writers would never visit Starbucks, and it's not that Word isn't the best tool for the job, because in some circumstances it demonstrably is.
No, the reason a lot of writers don't like Word is that it's made it so easy for Billy Bob Developer to write a decent looking document that people now think technical writing is easy, and oh my God is that fricking annoying!
No-one likes to feel that other people think their job is easy when you know that it's not. It's fair to say that some jobs are easier than others, and some jobs require more training that others, and I'm not going to suggest that writing a help file is more intellectually demanding than writing a compiler. But by the same token, I know someone who has written compilers, and his opinion was that writing the documentation for them was the most difficult part, because he could see everything in his head but he didn't know how to communicate it in writing.
As a professional writer, this pleases me. I like the validation that my job is not easy for some people. I like the fact that someone who does something I have no idea how to do considers my job the hardest part of his working day, when I find it the easiest. It's a nice feeling.
And then along comes a bozo who thinks they can do my job because they've worked out how to add headers and footers to a Word document.
It's
very easy to develop an irrational hatred of Word when you constantly
hear "Can't you just whip up a quick Word document?", or "Why can't you
just write it in Word?" and of course our particular
favourite, "Why is it taking so long? I could do it myself in 10 minutes in
Word!". There are many, many variants of these phrases and every
single one adds a small straw to the camel's back. Eventually, the
camel breaks down and from that point Word becomes "The Enemy". So
writers subtly, or not so-subtly, point out that "Of course Word is
good, but as a professional I use something different", the implication of course being that using Word is fine for amateurs, but not "proper" writers. The dislike of Word, ostensibly because it's not a professional tool, becomes a way of setting ourselves apart from non-writers.
It's a tribal thing, and snobbery about the way that people outside of your tribe do something is a key part of all tribes. For many writers, being snobbish about using Word is an identifier that marks them as a member of a tribe they want to belong to. It differentiates them, gives them an identity and a sense of collective, whilst letting them rail against Word as a proxy for all of the non-writers who don't understand what writers do and treat them accordingly. It doesn't matter how good Word actually is, it matters that it's a stick that some people use to beat us with. Or at least that's how it feels.
I'm not going to spell out the myriad reasons:
a) why Word is not always appropriate for what we do,
b) why Word doesn't have all of the functionality that we really, really, really need, and
c) why you can't do something better yourself in Word.
If you're reading this the chances are you either know the answers yourself or at least are smart enough to know that the answers are good ones. But next time you hear a writer railing against Word, just remember that once upon a time we were all Word fans....until it got too good.
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.
In Part 1 we looked at what ROI is, and how to calculate it.
In Part 2 we looked at the broad area of improving ROI by improving costs.
In Part 3 we looked in a bit more detail at direct costs, and specifically direct financial costs.
In Part 4 we looked at reducing direct time costs for other areas of the business.
In Part 5 we looked at creating a passive time income to save you time in the future.
In Part 6 we looked at ways to save time by using production line efficiency.
In part 7, we're going to look at ways to save time by improving your personal productivity.
As has been mentioned on many occasions in this series, time = money. When it comes to you, it's your time, which means that everything you do costs the company money, because they're paying for it. More than that, if you want to be a effective employee (or director, or company owner, or contractor, or hobbyist) you will need to have at least some basically efficient personal routines and habits to prevent you spending time on things which you either shouldn't or don't have to do. This is where the concept of personal productivity is useful.
Personal productivity means different things to different people but for our purposes, where we're looking at improving documentation ROI, it means using your time efficiently and effectively to maximise your writing time. The more time in the working day you can dedicate to researching, learning, writing, reviewing, proof reading, and all the other things that us writers have to do, the more documentation you can produce, and the higher the quality of that documentation.
With that in mind, there are 2 main areas that are worth investigating to see if you can save yourself time or make better use of non-writing time:
- Time Management - This has 2 core components: you, and other people. Managing your time well means cutting out interruptions, distractions, intrusive communication media and task switching as much as possible. All of these problems are caused either by you (especially distractions and task switching) or other people (especially interruptions and intrusive communication media). The goal of a time management system is to spend your time working on the most important priorities, not whatever is deemed most urgent by the other people interrupting you, and to spend that time in blocks large enough to allow you to focus properly.
- Task Management - This is the art of capturing, processing, doing and reviewing tasks, whilst using planning and prioritising to make sure you do the right tasks, at the right time, in the right order. Task management covers both repeating tasks (either regularly or irregularly) and one-off tasks. The difference between the repeating and one-off tasks is that whilst you can build an effective methodology for getting from start to finish that works for both types, you generally only have defined routines and habits for repeating tasks. This is for the obvious reason that by definition there can't be defined routines and habits for one-off tasks.
A lot of personal productivity training will focus on getting the right things done without wasting time on unimportant or unproductive tasks. The definition of "the right things" will be different for different people, roles and situations. For a personal assistant, emails, phone calls and calendar organisation are the right thing to focus on. For a professional technical writer those things will be the wrong thing to focus on, at least most of the time. Ultimately, the decision on what are the important and productive tasks is entirely contextual, but I'm going to assume that the right thing for you to focus on is producing high-quality documentation (including the non-writing tasks such as information gathering that technical writing requires).
To that end, the specific skills to develop are:
- Communications management (emails, phone calls, IM, social media);
- Capturing and processing tasks into a system;
- Assertiveness;
- Effective communication;
- Saying No to people;
- Managing expectations;
- Prioritisation;
- Planning.
And the general skills to develop are:
- Understanding the power of building and maintaining routines and habits;
- Why building a system is useless unless it works and you use it;
- What motivates you to get things done;
- What motivates others to help you (or leave you alone);
- How to achieve a state of flow;
- How to not panic or have a breakdown.
Depending on your current level of productivity and your work situation there will be other skills you need to develop, but these cover the majority of things which take away time and focus from the important work, and also the basics of getting that important work done. But bear in mind that getting a productivity system in place and working is like giving up smoking - you can use all the patches, sprays, and other aids you want, but ultimately willpower is required. Don't fall into the trap of thinking that the system is the important part, because it's not. You're the important part. The systems you develop to make yourself more productive are only useful if a) you use them, and b) they actually make you more productive. One of the easiest mistakes to make is to spend more time finessing the system than actually using it. This is particularly easy when you're something of a perfectionist or you have a tendency to get deep into the detail rather than the big picture. Keep the ultimate goal of increased productivity in mind. Tweaking your system to the nth degree is not productive.
If you've noticed that nowhere in those bullets points does it mention anything to do with writing skills, help authoring tools, or anything else that is specifically related to producing documentation, then congratulations and have a gold star on me. It's a fair question to ask: How can I talk about personal productivity as a writer without mentioning writing?
The equally fair answer is: Because I'm not talking about how to write productively (or well, or better, or more efficiently), I'm talking about how to consistently create and maintain the conditions you need to write. What, why, how and when you write is up to you, although of course I'm not averse to throwing my two penn'orth into that discussion. But that's for another time. This is about getting you set to write and that's enough for now.
Getting back to the point of this article: Calculating the ROI of personal productivity can be tricky, but it requires the same calculation as any other project: Work out the time it takes to build the systems you need, work out how much time they'll save you over a defined period, and plug the numbers into the equation. However, in this instance it might not be worth performing this exercise unless you need to justify what you're doing, because the return will be difficult to predict and you are unlikely to need budget approval for an activity that shouldn't require much if any outlay other than your own time. And, if you're serious about being more productive, a lot of the thought that needs to go into the system can be done on your own time.
I'll be covering all of these skills in a future series, but not as part of the series on ROI. If you want to crack on with improving your personal productivity, there is a slew of personal productivity information on the web. When I made that search, there were over 35.3 million results returned, so there's plenty of resources to help you. Good luck, and like all things in an agile world, don't be afraid to inspect and adapt to make the systems work for your personal system.
A more normal service will be resumed in part 8 of this series, where we'll switch from looking at saving costs to actually generating revenue.