On Writing, Tech, and Other Loquacities

The collected works of Lana Brindley: writer, speaker, blogger


Leave a comment

Facebook, Dynamite, Uber, Bombs, and You.

This is the transcript of a talk I gave at WriteTheDocs Australia, in Melbourne, on 15 November, 2018. A video is also available, see the Videos page for a link.


This little story starts with the American son of German migrants, Herman Hollerith. He was born in 1860, got a degree in engineering, and then went to work in the US Census Bureau in 1879. At that time, the census was just a headcount, they didn’t collect any real data on the population, simply because they didn’t have the ability to process that information. As it was, they only ran a census every ten years, and it took them several years to process all the information. This meant that the big concern of the department is that before too long it was going to take them longer than ten years to do the calculation, meaning the next census would have started before the last one was complete. 

These days, we call that overwhelming technical debt.

So young Master Hollerith was a bit of a bright spark, says “there ought to be a machine for doing the purely mechanical work of tabulating” and set out to build one. By 1884, he had a prototype, and the US Census Bureau used the machines for the 1890 census.

Herman Hollerith, Bright Spark.

The data is first encoded on the punch card with the pantograph, then operators would load the card into the tabulator. Pins would drop down onto the card, and where there was a hole the pin would drop through and land in some mercury, which completed an electrical circuit, and advanced one of the dials on the machine. So each dial on the machine represents one character trait: age, gender, state, etc. Then the operator would record the data, remove the card and put it into a sorter drawer. Then they could reset the tabulator, ready for the next one. According to the US Census history site, operators could process 80 cards a minute this way.

Because Hollerith was a bit of a smarty pants, he didn’t sell the machines to the government, he leased them, and after a bit he managed to lease them to all sorts of government departments, all around the world, which was good to keep the money flowing in in between censuses. To handle this, he created a company called, creatively, the The Hollerith Electric Tabulating System.

Over the next few years, Hollerith’s company found other companies that were making “machines” like employee punch clocks and weighing systems, and they merged into a partnership called the Computing-Tabulating-Recording Company (CTR). That company then became International Business Machines in 1924, and the companies were finally all merged in 1933.

Anyway, there is a whole other talk on IBM corporate history, but the short version is that Thomas J Watson became IBM chairman in a ridiculously dodgy deal in about 1914 WHILE HE WAS IN JAIL, and remained so until he died in 1956. Because the guy was so dodgy, he didn’t like writing things down. I mention that, because it becomes important later in the story.

IBM Dehomag Hollerith D11 Tabulator

These are some early IBM machines made by the German IBM subsidiary called Dehomag. These machines were called the Dehomag Hollerith D11 tabulator and sorter. They were originally used primarily in banks to process account transactions, calculate interest, and – most interesting to the government of the day – cross reference bank account numbers to census data.

This was in about 1935.

IBM Dehomag Hollerith D11 Sorter

You know when you see pictures of people who have been in the concentration camps, and they have a number tattooed on their arm? Those numbers connected the human being to the punch card for a Hollerith machine. So here’s a fact: In Holland, they had extensive Hollerith machine infrastructure in the years before the war, and 73% of Dutch Jews were killed by the end of it. In France, they had very little Hollerith infrastructure, and what they had was disorganised. Only 25% of French Jews were killed by the end of the war. In short, without this technology, the Holocaust would still have happened, but it wouldn’t have been so well organised, so well planned, and so well executed.

Of course, I’m sure you all know about the Nuremberg Trials that happened after the war ended. We remember those for the Nazis who got sentenced for war crimes in the main trial, but there were 12 more trials between 1946 and 1949, which covered 177 people: physicians, judges, military personnel, civil servants and also industrialists.

Gustav Krupp and his friend Adolf Hitler

People like Gustav Krupp, who provided Panzer Tanks to the Nazis. Interestingly, it didn’t slow that company down much: you probably know them as ThyssenKrupp now. They make elevators. Anyway, so you would expect that senior officials in IBM would have ended up before the Nuremberg trials, too, but jokes on you!

The Nuremberg Trials were pretty unique, in that they had to be conducted in four languages, more or less simultaneously, which had never been done before. Guess who provided the computing power for that? Got it in one! Interestingly, for completely unrelated reasons, I was in Nuremberg a couple of months ago, and took the opportunity to go to the Documentation Center and Nazi Party Rally Grounds. It was a fascinating tour, but much to my dismay, IBM was not mentioned once.

Hopefully what you’ve picked up so far is that Hollerith was a brilliant young man who solved a very difficult problem. It’s not his fault that the technology he developed was used by Hitler to murder people. It’s also not his fault that not only was no one held responsible for that, but also that we seem to have collectively forgotten about it. The point I’d like to make, here, is that throughout history technology has been used in some pretty horrible ways. So let’s look at some more historical “oh no” moments …

Alfred Nobel, Repentant “Merchant of Death”

Alfred Nobel, you might recognise his name. He was the guy who invented dynamite, but he also owned a large weapons manufacturing plant. Anyway, Alfred’s brother died in Cannes, and a French newspaper got confused and wrote an obituary for Alfred instead. It was pretty nasty stuff, titled “The merchant of death is dead”, and this wonderful line: “Dr. Alfred Nobel … became rich by finding ways to kill more people faster than ever before”. So Alfred read this, had what is technically known as an oh no moment, and completely secretly went on to establish the Nobel prize with his personal fortune. Hilariously, he decided not to tell anyone about it, so they all got a nice surprise after he died for real, and they read his will.

Otto Hahn got the Nobel Prize for Chemistry in 1944 for working out Nuclear Fission. The prize really should have been given to him along with his two colleagues Lise Meitner and Fritz Strassmann, but the other two had had to leave Germany in a bit of a hurry a few years earlier. Later on, of course, that technology was used to bomb Nagasaki and Hiroshima, and the entire world had an oh no moment. Now we have ethics committees in Chemistry.

Eugenics was the practice of sterilising portions of the population in order to stop them breeding. Hitler was obviously a big fan, but before WWII it was a bit of a big deal in the US. 33 US states had sterilisation programs in place against mentally ill people, disabled people, alcoholics, people living in poverty, and people deemed to be promiscuous. Some reports say around 65,000 Americans were legally sterilised during the first half of the 20th century. That was a bit of an oh no moment for Biology. The World Health Organisation (WHO) was created in 1948, as the first specialised agency of the UN. It’s mission was multi-faceted, but I’ll draw your attention to this bit: “to address the underlying social and economic determinants of health through policies and programmes that enhance health equity and integrate pro-poor, gender-responsive, and human rights-based approaches”. 

Basically, don’t let our government kill you and tell you it’s good for  your health.

In a similar vein, some great drug failures like Thalidomide made the idea of having better oversight on medicines seem like a good idea. Thalidomide was sold over the counter from 1957, and was recommended to pregnant women for relieving the symptoms of morning sickness, unfortunately it created horrific birth defects. Only 40% of children born with defects survived, and those who didn’t were missing limbs. oh no. Court cases were brought against the manufacturer all over the world, including a class action in Australia as recently as 2012. The US Food and Drug Administration was created in 1927, but the thalidomide cases significantly strengthened its abilities, and a whole bunch of other laws around the world were introduced to address drug testing around the world.

We didn’t let too many bridges collapse before we decided that civil engineering could use some regulation. In America, the National Society of Professional Engineers was established in 1932, which adopted a formal code of ethics in 1964.

And it only took one plane flying into a building to establish that maybe letting people take box cutters on planes was less than sensible.

Hopefully you can see where I’m going here.

People very rarely come up with new ideas, new inventions, amazing new discoveries, with the intention of killing or hurting people. It’s the unintended consequences that cause the problems. But it’s also those unintended consequences – the “oh no” moments – that lead to improvements in the way we handle things. We end up with better laws, better regulations, and our society improves as a result.

Ethics committees and government oversight departments and legal rulings don’t stop bad things happening. But they can certainly help prevent them, and at least they give us some kind of recourse if the worst happens.

Now, I want you to consider these two cases: Volkswagen was caught out having written software code that allowed their cars to cheat emissions tests.

Uber also developed software (called ‘greyball’) which allowed them to cheat law enforcement officials trying to crack down on ride-sharing.

The difference is that Volkswagen software engineers went to jail, and Uber software engineers didn’t. Why? Because one is a car company, and one is a software company.

Startups especially like to use the phrase “move fast and break stuff”. In IT, we talk about “innovation” a lot, and “thinking outside the box”. I’m sure we all know a project manager who has encouraged us to “challenge paradigms” or “think different”. This is all great, and I’m not suggesting we should stop building new things, or thinking up interesting ways to tackle problems! But what happens when we step back from what we’ve created, and go … oh. No.

Really, in my opinion, IT should have its oh no moment when IBM provided the computing power that made the Holocaust possible, but not only did it go unpunished, we’ve largely forgotten about it over the intervening 80 years or so. So there’s never really been a public reckoning. So now we’ve looked at some examples of oh no moments leading to real change, let’s look at some aspects of IT innovation that haven’t …

The development of the world wide web in the 90s was obviously very optimistic, and I’m not sure we can blame anyone for failing to see 4Chan coming. But we can probably blame some of the social media sites for failing to see the dens of iniquity they have become, and we can certainly blame most of them for failing to do anything about it once it happened. Twitter’s response to the incredible amount of white supremacism has been at best ineffective and, at worse, non-existent.

I find self-driving cars a particularly thorny problem. On the one hand, there are huge benefits to the technology. Consider the implications not only on the environment and on the convenience it can add to our lives, but the added mobility and independence it would give people with disabilities means that this technology could add so much to our lives and to our society. But we haven’t fully thought through the impacts yet. Most of the accidents related to self-driving features so far have been because humans became too reliant on the tech, doing stupid stuff like watching movies, reading, or napping, instead of acting as a last-resort safeguard. What happens when we rely on the tech so much that we stop looking before we cross the road, because we “just know” the cars will stop for us? I have self-driving features in my car, and it makes stupid mistakes ALL THE TIME. The tech is not advanced enough for us to rely on it – driving is, after all, a life or death proposition every time you get on the road. But I also don’t think it should be hidden away until it’s perfect, because how else do you learn what “perfect” is? This is a tricky one.

I looked into the killer robots thing a few months ago, and that’s another tricky one, because the technology being developed for fully-automatic weapons systems, is also used for things like the afore-mentioned self-driving cars, aeroplane technology, medicine and surgery applications, and even peace-keeping operations, like dropping aid packages into war zones. In this case in South Korea, a university went into partnership with an arms manufacturer to develop autonomous weapons, and what ended up stopping them was a bunch of universities signing an open letter (which was initiated by an Australian academic, incidentally), threatening to boycott the university involved. The South Korean government wasn’t intending to step in, the UN didn’t step in. Without an ethics organisation, what other recourse is there to stop things? As it is, we don’t really know that the research has been stopped. The chancellor of the university wrote a lovely letter saying that, but the weapons organisation funding it could be quite happily moving along, and I wouldn’t be at all surprised if they had waved large amounts of money at academics to bring them into the project. That’s all speculation of course, but that’s really my point: there’s no oversight, no regulations, no repercussions, but there is a hell of a lot of money.

Here’s one more for you, that was reported in the Economist a couple of months ago, and has been picking up pace in the mainstream media recently: Xinjiang is a province in north-west China, largely occupied by the Uighur people. So, the Uighur are the largest Muslim group in China. In Hotan, the capital of Xinjiang, there is a police station every 300m or so. If you don’t think that already sounds like a police state, wait for this bit: every citizen has an identity card, and at checkpoints around the province, police will scan people’s cards, take photographs and fingerprints, perform an iris scan, and are told to unlock and hand over any smartphones, which are put into a cradle and the data downloaded to be analysed later on. That’s not just for people they’re suspicious of, they’re for everybody. There are four or five checkpoints every kilometre, with citizens moving through them many times a day. The roads are lined with poles holding cameras which watch pedestrians, but also perform pattern matching between number plates on cars, and the faces of the people driving. And if you’re Uighur and you have done even a relatively minor infraction then you get sent to one of hundreds of thousands of “re-education” camps in the province, which don’t officially exist. No one really knows how many people are locked up, but the estimate in the Economist article was 140,000 people in Hotan alone. The ABC in recent reporting says 2 million. So, locking up minority groups for no reason is by no means a new thing, but the way technology is being put to use in this case certainly is. I bet the people who invented facial recognition have had several oh no moments thanks, at least in part, to China.

In that same vein, you might also have heard of Palantir. They’re the company that use Minority Report-style predictions about crime in an area. It was originally developed for the Pentagon to identify terrorists in Iraq, but that technology has now been imported to downtown Los Angeles, where it’s being used to lock up brown people *before* they commit a crime. So it’s not just China.

So, while the increasing mainstream media awareness of personal data and the nefarious purposes we can put it to has been heartening recently, I’m not sure that Cambridge Analytica and Facebook are enough to be considered an oh no moment that will actually change anything in our industry, but I think it might be starting.

So, what does all this have to do with documentation?

You might be aware that, after quality assurance, the group that finds the most bugs in software is the documentation team. We are often put in the position of poking at products we don’t yet fully understand, in order to work out how to use them. It is the writer’s job to come at products like a clueless user, poke things, bend them, use them in ways they haven’t been designed.

I say we should expand that thinking just a tiny bit: how could I use this product to do harm? How could I use it to discover things about people I really shouldn’t be discovering? Can I use this social product to stalk my ex? What about someone who said something nasty about me online, can they find out anything important about me? Can I use this platform, this API, this plugin, this app, this feature to do something that, as reasonable moral human beings, we feel a little uncomfortable about? It’s also important to think about using it in conjunction with other tech. Recognising someone’s face is one thing, but when you combine that with GPS locations, government databases, and purchase history, you have a completely different problem. And also an answer to why I stopped using supermarket loyalty cards. Only last week I received an email confirming my booking for a hotel I hadn’t heard of. Curious, I clicked the link to ‘edit my booking’ and discovered that, while I couldn’t see the whole credit card number, I could have adjusted the dates of the booking, upgraded the room, or purchased additional services. All because someone mistyped their email in a form.

If I can give you one piece of advice, it’s don’t read your marketing department’s hype. Or if you do, don’t believe it. Nuclear fission has saved millions of lives through cancer treatment, provided light and power to billions, and made surgery and even vegetables safe through irradiation, that’s what the marketing department want you to know. But it also made nuclear war a real possible threat, and the marketing department is unlikely to mention it.

So, question things. Raise bugs. 

Talk about it with your development team, and your manager. Until software engineering has a real, honest to god, oh no moment, and an ethics board with actual legal teeth is born, you — the tech writer — are at the forefront between technology that helps, and technology that can hurt.

Share


Leave a comment

OpenStack Newton Summit – Docs Wrapup

Everything is bigger in Texas: including the conferences!

DSC_1078

This Summit was a homecoming of sorts. OpenStack started in Austin with 750 people, and returned six years and twelve conferences later with 7500 people. Even the baristas in the downtown coffee shops noticed us the second time around.

For documentation, this conference was bigger than usual as well. We had a total of eight sessions, in addition to the contributor meetup on the last day, which is more docs sessions than we have ever had before.

And we had a lot to talk about! The biggest thing on our minds was the future of the OpenStack Installation Guide. The Big Tent has changed the way that projects go about joining the OpenStack ecosystem, and with Foundation having an increased focus on ensuring new projects have sufficient documentation, we needed to change our approach to documenting the installation of an OpenStack cloud. There is no ‘right’ way to install a cloud any more, and there is certainly no ‘right’ set of components you should be installing when you do it. But with a small documentation team, and a seemingly endless parade of new components requiring documentation, we were faced with a big technical challenge, where everyone had some kind of skin in the game. Despite some differences of opinion, the session itself was extremely productive, and we came away with a solid set of deliverables for Newton. First of all, we’re going to create the infrastructure to allow projects to write their own installation docs in their repos, and then publish them seamlessly to the docs.openstack.org front page. This means that projects have responsibility for their own docs, but the docs team will provide assistance in the form of templates and infrastructure support to ensure that all projects are treated as first class citizens. Secondly, the existing Installation Guide will change focus to be more about an installation tutorial, giving people a highly opinionated and completely manual installation method to learn the ropes, but not to install a production cloud. Thanks to the OpenStack User Survey, we can safely say that most production clouds are installed using some kind of automated tool, so having manual installation instructions is useful as a training tool, but not in a real world scenario.

With the big question more or less settled, we got on to the fairly long laundry list of other things that needed to be done, which all ended up focusing mostly on streamlining some of our processes, being clearer about the way we operate, consolidating guides that had (for obscure historical reasons) been in their own repos into the main one again, and general editing and tidying up. A full list of the goals can be seen here: Newton Docs Deliverables. And, for historical interest, here’s the whiteboard from the Summit session:

DSC_1099

During the Mitaka release, docs had a focus on Manageability, aiming to work more effectively and efficiently, with a focus on collaboration. For Newton, while manageability themes are still very much present, the focus is more on Scalability, and making our documentation efforts scale out to represent a much greater proportion of products, contributors, operators, and users. From empowering projects to write their own documentation with our support, to making our processes simpler to find and understand, to ensuring our documentation is as accurate, up-to-date, and effective as possible, it’s going to be an exciting cycle for docs!

I leave you with one of my favourite Texan big things: a bathtub margarita!

DSC_1074

Share


Leave a comment

Content as a driver of change – Then & Now

Humans have always written things down.

Those of you reading this post, with your laptops, and mobile phones, and iPads, and vanity email accounts, and your single sourced, content-reuse, DITA-compatible Docbook XML toolchains, with all your fancy Javascript elements and mind-boggling CSS overlays. You are just the latest in a long line of human beings who have been doing the same thing for millennia. Albeit with different tools.

Panel_of_simple_figures_with_boomerangs_-_Google_Art_Project

The original owners of the land we are standing on today are the Wurundjeri people. Australian indigenous art is the oldest unbroken tradition of art in the world. These weren’t just the pre-history version of hanging a Monet print on your loungeroom wall. Indigenous art exists on all manner of things: paintings on leaves, wood and rock carvings, sculptures, and of course cave drawings. This art gave early Australians a way to record the things that mattered most to them in their lives: they often involve scenes of hunts or special ceremonies. In the case of Australian art, many include megafauna and other extinct species, and even the arrival of European ships. More than a record of events, though, they were probably also a method of teaching. Each indigenous tribe had its own mythology (collectively known in English as ‘the Dreaming’), which used stories to convey morals or other educational information. Most children who grew up in Australia would be familiar with the Dreamtime story about Tiddilik the Frog, a fable about greed and about finding humour in bad situations. Indigenous art and the stories that lie behind them are really just an early technical manual for life itself, especially in a world where living for any length of time could be quite difficult.

De_Architectura027

Who here remembers the story of Archimedes and his bath? It’s a demonstration of how Archimedes used water displacement to measure the density of an object (in this case, the king’s crown). Of course, the bit we all remember of the story, though, is that Archimedes, having made his discovery in the bath, went running naked through the streets of Syracuse, crying “Eureka! I have found it!”. This story comes to us from one of the oldest surviving technical manuals in existence, the “De architectura” by Marcus Vitruvius Pollio, which was published in around 15BC. Of course, the Ancient Greeks & Romans were well known for their literature, their scholars, their philosophers, and perhaps above all, their library. The Royal Library of Alexandria in Egypt was the largest repository of knowledge in the world between the 3rd century BC and 30BC. The famous fire that destroyed it was probably set by Julius Caesar himself in 48BC, but the library continued in some capacity until the Roman Emperor Aurelian destroyed what remained in about 270AD. This was of course a massive blow to literature, but it also an incredible loss of technical data as well. Thankfully, the Ancients managed to keep going even after the library was destroyed, and we now have surviving copies of wonderful pieces like Pliny’s Naturalis Historia, which is essentially the world’s very first Natural History encyclopaedia, and which set the stage for many more technical manuals to come.

Gutenberg_Bible,_Lenox_Copy,_New_York_Public_Library,_2009._Pic_01

Jumping over to Europe, Gutenberg did his thing with the printing press in the mid 1400s, but printed books were still a terrifically rare and expensive thing until well into the 15 and 1600s. Up until that period, if you were a fairly ordinary person in a fairly ordinary European town, you were probably aware of the existence of almost exactly one book: the bible that your local clergy had sitting on a plinth in your church. You probably couldn’t read yourself, or if you could probably not well enough to be able to read and understand a book written predominantly in a particularly stuffy version of Latin, and even if you could read that well, you wouldn’t be allowed to touch it. No, the bible was the word of God, and as such could only be read and interpreted by men of the cloth. They didn’t really want people going off and reading the Bible on their own and drawing their own conclusions about things. Of course, this got really interesting once the Reformation really started to get underway in the mid 1500s, and people started to read the Bible for themselves. In fact, for a little while there in England, Henry VIII decided that ordinary folk (and all women) were banned from reading the Bible. All this running around reading things and learning by everyday people was just a little too much for him to bear, especially when they started disagreeing with him.

Marianne_Stokes_(1855-1927)_-_-The_Frog_Prince-

Still in Europe, with better access to mass printing, publishing written versions of early verbal history became the thing to do. We all know the Brothers Grimm were writing fairy tales in German in the early 1800s, but they certainly weren’t the first to try and document the oral history of early Europeans. Charles Perrault is considered the original author of many of the Disney favourites, including Cinderella, Little Red Riding Hood, and Sleeping Beauty, and he was writing in French over a century before the Grimms, in the late 1600s. But even he was just writing down stories he’d heard from others. My favourite version of Cinderella comes from Giambattista Basile, published in Neapolitan in 1634, some years after he died. These stories, gruesome as they were before Disney got a hold of them, were intended in many cases to be fables for children, with a moral story, but were also used as cautionary tales for adults. In Basile’s version of Cinderella a husband is warned of the horrors of not being too picky about your second or third wife, he gives a general warning to the household about choosing your housekeeping staff carefully, a warning to parents about treating children fairly, and a warning to young women about being proud. And that’s before we get to the bit Disney likes: “if you’re a good person, good things will happen to you”. Some versions of the story also slam home the opposing moral: “if you’re a bad person, bad things will happen to you”, with both the step-sisters either mutilating their own feet to fit the slipper, having their eyes pecked out by birds at Cinderella’s wedding, or some equally terrible combination. As for other horrifying fairy tales, anyone who has read anything by Hans Christian Anderson will know that they often got worse before they got better. There’s a reason Disney never took on “The Little Match Girl”. For a long time, what we now know as fairy tales were the easiest and most entertaining way for a largely illiterate population to record and share moral stories and warnings.

geisha_maiko

A ribbon that runs through all of these is the idea of the master and apprentice. These types of relationships began in Europe in the 1300s, and were a way for a trade person to get cheap labour, while a young apprentice got a bed to sleep on, food to eat, and the hope of a trade later on. This system was used throughout England and Europe for all skilled trades: from seamstresses and blacksmiths, to Knights with their squires. However, the general principles of apprenticeships exist throughout the world, with one of the earliest examples being the idea of a Maiko, or a trainee Geisha. Geisha have existed in Japan since around 700, and still take in Maiko to this day. While this isn’t written knowledge, it is an important footnote when we’re discussing the history of content, as this was the main way that specialised technical knowledge was handed down.

JamesCampbell_NewsfromMyLad

Of course, a young apprentice, wishing to remember all the things they had learned, might be inclined to write them down. By the time the Industrial Revolution was in full swing, paper and books had become affordable, schooling was more available to children throughout Europe, and literacy was becoming much more widespread, especially to those bright young apprentices who left home to seek their fortunes. And while young people have written home to their families since ancient times, letter writing really hit its stride around the turn of the century when it became not just a way to record their days and connect with their families, but also a way to explore political and religious matters, and explore emotions: poison pens, love letters, and obituaries are all well represented in letters. Another form of writing more like the manuals we know today of course, is the recipe book. Many household cooks would enshrine their recipes in writing, to be handed down to the next generation. I regularly bake a family choc chip biscuit recipe that has been handed down mother to daughter for at least five generations, and possibly quite a few more than that.

But enough history. The older writers in the audience will probably remember most of these more recent forms of technical communication. Some of the more unfortunate among you may still be working with some of them. In that case, I’m sorry.

oreillybooks

Printed books are pretty all of our yesterdays. In some ways, it still feels as though you’re not a REAL writer until you’ve got your name on the outside of an actual book, made out of dead tree, and sent from some printer. I chose a picture of O’Reilly books on purpose, as OpenStack released yet another of our manuals as O’Reilly dead tree version last year, although we have no immediate plans to repeat that in a hurry. Personally, I’m part of the problem here. I love having dead tree reference books, especially for things like Style Guides, which are somehow easier to have sitting on my desk as I write, rather than relying on an internet search (which can, for me, at least, be very distracting. Hello, Twitter!). As for writing them, though? No, I love the idea of being able to catch and fix errors even after publication. Nevertheless, printed books, especially technical manuals, are our history, our present and, to some extent at least, probably also our future.

SONY DSC

SONY DSC

A close cousin of the printed manual, whitepapers are caught somewhere between marketing material and technical documentation. In digital form, they are probably not going to go away any time soon, but the printed whitepaper has almost certainly been confined to the recycling bin these days. My very first piece of technical writing was a white paper. I had a Marketing undergraduate degree and half an MBA, so it was a fairly logical piece of work for me to be doing at the time. I enjoyed it immensely, and immediately set out to become the whitepaper expert, intending to build a career around it. Thank goodness I discovered technical manuals in the meantime, and was saved from a life of writing whitepapers!

onlinebooks

And, finally in the ‘recent’ category, I have a screenshot from my very own project. This is, for all intents and purposes, an online version of a printed ‘book’. It has a table of contents down the side, divided into chapters and sections, and it’s designed to be read from beginning to end: simple concepts at the beginning, more complicated procedures as you move through, with reference information (tables of data, contact details, and a glossary) at the end.

These have all been great methods of getting information out there, but they are all destined to become as archaic as the fairy tales and the cave paintings we discussed earlier. Let’s take a look at those things we’re doing a little differently today, that will drive the way we revolutionise and improve content management in the future.

webcast

First of all, I want to briefly touch on MOOCs. These are the future of face to face training courses. MOOCs not only allow people all around the world to study when and where they choose, but they also allow institutions to create online tool that mimic real world scenarios, and allow students to learn real skills in a safe environment. This is great especially for the tech industry, where students can work on realistic IT setups that they might not be able to recreate in their own environments, but it also works well for teaching other knowledge work skills such as customer service and financial skills.

DITA_finch

The main thing that, I think, changed the way we looked at the information we were creating, was DITA. Of course, DITA isn’t new. It was named in 2001, and formalised in 2005, but varying groups have been working on data mapping and the like since the 60s and 70s, and it became especially popular in the 90s, with the publication of JoAnn Hackos’s book ‘Managing Your Documentation Project’ (and later ‘Information Development’) a book probably most of us have on our shelves, and to which I (at least) still refer to regularly. DITA was really the first formal, open standard that let us consistently and accurately categorise data into formal types. And it was simple enough that we could all use it, remember it, and above all teach it to others easily. Even if you’re not using a specific DITA tool, the general principles of DITA–splitting content into one of only three data types–could be used to underpin any tooling system.

Of course, the main driving principle behind DITA (besides the categorisation) is about content reuse and single sourcing. This is another key component of how we’re changing the way we look at content. It’s not about a beginning and an end any more. With this idea, we walked away from the age old idea of delivering a story, and moved towards this critical period of considering what information is required where, and when. This was important mostly because we were actually starting to consider how people consume information, and learned difficult concepts. We no longer assumed that information we gave to people in the beginning of a book stuck with them as they moved through the rest of the content. Sometimes, learners needed to go over information again and again before they actually learned it and could apply that information to later, more complicated, tasks. And, being the inherently lazy writers that we are, we didn’t want to retype that every time. So single sourcing and content reuse were naturally very easy for us to adopt.

And that leads me to perhaps my favourite topic right now: every page is page one. This is a model designed by Mark Baker, and while his model is certainly not the only one out there, it’s certainly one of the best developed. The general idea behind this is that no piece of content is more or less important than any other. It’s not quite DITA, in that a ‘page’ in EPPO terms is much bigger than a ‘topic’ in DITA terms. The best example comes from Baker himself, where he refers to a recipe. A recipe contains, in DITA terms, a concept (some information about the recipe, that describes what you’re actually creating, and maybe some background, where the recipe has come from, and the types of ingredients that you need), followed by a procedure (the actual steps of the recipe), and finished with reference information (serving suggestions, maybe information on converting measurements, or ingredient substitutions). In EPPO, the entire recipe is the ‘page’: it contains everything you need to be able to perform the task, including all that concept and reference info. One of the best ways to think about EPPO is in terms of a Wikipedia page, there are links to further information if you need it (and I’m sure all of us here have gotten sidetracked by clicking those links in a Wikipedia article!), but that page contains all the specific information about a particular topic. There is no beginning to Wikipedia, and there is most certainly no end.

mrsduffeekindle_crop

So this leads me to the big question: what does the future hold for content? I think there are a few main themes we can tease out of our little journey through documentation:
The internet is making things possible that never were before
Control over content is shifting from those producing it, to those consuming it.
Consumers are used to being able to search vast resources for content, and filtering those results themselves. They don’t want us to tell them what they need to know.

Since well before the birth of Christ, in one form or another, we’ve been writing stories. Now the internet allows people to create their own stories, not just have one told to them. In many ways, this shows a maturation in human development: we’re no longer willing to receive whatever is fed to us, we want to create our own realities, and we have the tools to be able to do that.

But that is a massive challenge–and (I would argue) an opportunity–for technical writers. We get to break new ground, and thankfully we’ve been working on the building blocks of this type communication for a few decades now. The challenge now is to start delivering documentation in a completely new way, without leaving our organisations, our management, or our more stubborn clients behind. Nobody said breaking new ground would not require effort, or determination. As we shed old ideas, old processes, old technologies, and old systems, there will be people who decry change, and impede our progress. But even if you only manage to implement a small piece of your grand vision, even if all you ever get to do is plant a seed of an idea in someone’s head that maybe–just maybe–there’s a different way to do things, then you have succeeded. After all, every one of the pieces of content I have mentioned here had its detractors, from every day ‘concerned citizens’, right up to royalty, and the literati.

public-domain-images-free-stock-photos-autumn

I mentioned Archimedes earlier, but now I would like to pick a different quote of his: give me a lever and a firm place to stand, and I shall move the world.

Right now it seems to me, that where we could go next is almost infinite. People have always created and consumed content. As long as we continue to put the information out there, and give people the tools to find it, they will continue to do so. We are not at the end of a journey, nor at the beginning of one. We are merely at a step along a very long road. Let’s find out where it leads us.


References: https://docs.google.com/document/d/10meNxWpeiyYprcQjOFIBZJlm3xEiWgarN5GVk1uhJOM/edit?usp=sharing

This was originally presented as a keynote at the Australian Technical Writers’ Association Conference in Melbourne on 23 October, 2015. No video recording exists of this talk.

Share


Leave a comment

linux.conf.au 2015 – Documentation Miniconf

Day 1 is drawing to a close at linux.conf.au 2015 and we’ve just wrapped the documentation miniconf. There was an interesting mix of talks today, and as the first documentation miniconf at an LCA, it’s given me some great ideas for growing the miniconf in future years.

As for me, after doing the Agile Documentation Lego talk at LCA in Perth in 2014, I felt I needed to give a good follow up show, this time focusing on Every Page is Page One. To do this, I devised a game based on the children’s book “We’re Going on a Bear Hunt”, and using Play-Doh to make it a little more hands on.

2015-01-11 (1)

Share


Leave a comment

The only writing sample you need is your resume

I came across this article recently, which states “code is the new resume”. It asserts that people seeking coding jobs should be contributing to open source and using those contributions as proof that they have the skills for the job they’re seeking. I wholly agree, but it got me thinking about the equivalent for writers.

When I have had prospective tech writers come to me for advice on where to start, I have always pointed them towards an open source project that I think would meet their skills and interests. I usually have three main reasons for this. I want them to get experience working with processes within a docs team (particularly a mature docs team that functions well, such as Libre Office or OpenStack). I want to give them an opportunity to get familiar with the tools and programs used by highly technical writing projects (things like Docbook XML and Publican, rather than proprietary tools like Madcap or Adobe). And, perhaps most importantly, I want to give them a chance to write things that they can share with prospective employers.

But contributing to open source docs, while beneficial in career terms, rarely ends up being something you can confidently wave in front of an employer. Rarely, if ever, will you get the chance to create a new document from scratch, something you can call truly yours. And even if you get that chance, rarely will it remain the piece of art you crafted for very long. Open source software moves quickly, and by the time you publish your meticulously researched and effectively written document, there will be a team of hungry writers circling, ready to rip into your virgin words and tear them apart. Within months, your perfect book could be an almost unrecognisable crime against information architecture, full of passive voice and typoed commands, with a title that no longer reflects its content. Certainly not something you want your name anywhere near.

Herein lies the tech writer’s dilemma: when asked for writing samples, what do you do? You don’t want to admit to authorship of something that (through no fault of your own) makes you want to quit the industry, but you also don’t want to say that you’ve been contributing to a project for months and have nothing to show for it. My answer: make your resume your writing sample. You won’t always get away with it, because some employers will ask for writing samples as a matter of course (at which point, having kept a tech writing blog for a while can be very handy. Just sayin’), but having plenty of prose in your resume and making sure it shows off your skills will do wonders for proving you can do the job.

There are no rules saying you need to deliver a two page resume, developed using a standard Word template, to apply for a job. Designers have been handing in creative resumes for decades, and we can take a leaf out their book. Offering something different, something that screams “I’m a writer, and I’m damn good at what I do” is going to make any recruiter or hiring manager stop and look. Remember how many resumes these guys see. Offering a bog-standard resume means that yours will get thrown away at the first typo.

shakespeare

First of all, do your research. If you can, find out what writing tools your prospective employer uses, and use it. If you don’t have that in your repertoire, then use the closest thing you can do. When I applied for my first job that used Docbook XML, I delivered my resume in LaTeX (complete with “Typeset in LaTeX and TeX” in a footnote at the bottom of each page. Nothing like rubbing it right in). I later found out that the hiring manager ran around the office showing it off to all his existing writers, pointing excitedly to the footnote. Once I’d learned Docbook XML, following jobs got that instead. If the company you want to work for uses Word, then deliver a beautifully formatted Word resume (and don’t forget to use styles!). By the same token, be aware of internal culture, and the fact that people get very passionate about their tools. Never deliver a resume built in Word with a .docx extension to an open source company if you don’t want to be teased about it forever after (assuming you get the job despite it, of course).

And, perhaps most importantly, don’t just deliver a series of dot points. This is your chance to prove you can write. Include a fairly long prose introduction, but don’t waffle. Be clear about your goals, the job you’re after, and any relevant work you’ve done previously. If you can, do some research into the company you’re looking to join, and tailor this part to the role you want. Mention how your experience meets their demands, not as a canned response to selection criteria, but as someone who has gone looking for core values and culture clues, and is addressing the human beings that work within that group. Write directly, succinctly, but passionately. Don’t use words too big for the subject (with apologies for paraphrasing C.S. Lewis), make your language casual, but not informal. Get your writer friends to proofread it until you are confident it is perfect. Feel free to email me with your text and I’ll also help.

Don’t make recruiters ask for writing samples. Get creative, use your skills to your advantage, and don’t be afraid to have some fun with it. If you have your own stories of resumes (good or bad), or hiring, please share!

Share


Leave a comment

OpenStack Contributions

Like most people I learn best by doing, so one of the first tasks I set myself when I started working on OpenStack documentation was to get a docs patch in as quickly as possible. In the end, this turned out to be a copyedit on the introduction to the High Availability guide, and it happened on day two, right before I did my induction in Sydney on day three. I had no idea this was a big deal until I got to the Sydney office to find myself being lauded, which was somewhat amusing, and slightly embarrassing.

Stackalytics_firstcommit

So the main upside of this is that I am now officially an OpenStack ATC (active technical contributor). The next step from here is to keep making patches of course, along with code reviews and the like and hopefully to continue being useful to the community in this way.

One of the more important things about coming to a new project is working out the workflows. All the formal stuff is documented, of course, but sometimes it’s the common knowledge things that are hardest to pick up; the bits that ‘everyone knows’. I’m still feeling a little daunted by code reviews (what exactly constitutes an acceptable patch? To what extent should I be testing the proposed content?), but after discussions with the core docs contributors I’m starting to get a handle on those. This week has been spent largely as a sponge: just trying to soak everything up. After a day or two off over the weekend, hopefully my brain has made sense of most of the things I’ve learned so far, and next week will be a week of action!

Share


Leave a comment

Linux.conf.au 2014 – Perth, WA

Possibly my favourite conference, linux.conf.au is coming to sunny Perth in January 2014. I’ll be returning to the Haecksen miniconf driver’s seat (check out haecksen.net for more info and the Call for Proposals), and also will be giving a talk myself, called There and Back Again: An Unexpected Journey in Agile Documentation. This is a talk I’ve given a few times already, including at OSDC 2013, so I’m really looking forward to sharing it with the linux.conf.au audience. That, and I’ve never been to Perth before, so yay!

linux.conf.au 2014 - Perth WA

Share


Leave a comment

Writing Effective Procedures

Writing procedures can be much more difficult than you’d think. We see procedures everywhere, so it’s natural to think that we should be able to write one without too much trouble. For that reason, I wanted to take you through some terrible real-life procedures. This is at least partly so we can all have a chuckle at other peoples’ mistakes, and feel a little bit better about ourselves. But it’s also because it’s a lot easier to find examples of bad procedures than good ones.

With that end in mind, I went through my junk drawer, and pulled out one or two manuals that I had lying around, and I’m going to use them as examples of what not to do as we go along.

The first thing you need to look at is whether you’re documenting a process or a procedure. It’s easy to use these terms interchangeably, but they actually mean different things. The main thing to remember is that a process can contain many procedures. A process gives an overview of tasks: you might need to install the package, configure the package, and then use the package. Overall, that’s a process. Each of those things, though, is a procedure. Procedures are instructions for doing something.

WriteProcedures

Here’s an example of a certain hand-held computer game. As you can see, the instructions for using the stylus are … step 5? Every procedure in this book is numbered. What’s happened here is each procedure in a process has been numbered, rather than each step in a procedure.

So the next thing to worry about is whether you should be using bullets or numbers. This one is a really simple test: is the order important? If the order is important, use numbers. If it’s not, use bullets. Oddly, though, we get this one wrong all the time …

WriteProcedures1

These ones should all be bullets. You don’t need to operate the product from a power source before you remove the unit from the packaging.

WriteProcedures3

Let’s try this one together: Most of these ones should be numbered, the text even tells us that. The ones on the left under “Cutting Tips” are bullets, the order isn’t important, it’s a list of tips. What about at the top under “Starting and Stopping the Trimmer”? This one probably doesn’t matter, I’d be inclined to use numbers, though, mostly because you can’t stop the trimmer unless you’ve already started it.

WriteProcedures4

And just another one, because it’s so easy: The bullets in red are fine, but then we go to numbers in the purple, and then for a little variety we throw in some upper-case letters in green. Bullets would have been for all of these.

So the next thing to worry about is whether you’re describing a concept or a task. A concept is a description, it answers the question “What do I need to know?”. A task is an action, it answers the question “What do I need to do?”. As writers, it’s much easier for us to think about things rather than tasks. Users think about tasks, though, not things. Remember the old adage about not needing a drill, but a hole? That’s the essence of this point.

WriteProcedures5

This one just has so much wrong with it it’s hard to know where to start. Considering we’re talking about concepts and tasks though, let’s start with pulling those out. I’ve marked the concepts in blue, and the tasks in purple. To add insult to injury, we also have numbers where we should have bullets (in red), because this really is such a hodge-podge of information that there’s no way the order is important. Just to round things off, we also have a typo, and a vaguely insulting term about our children (in yellow).

But looking at that brings me nicely to the next point, which is about the level of detail. Make sure you don’t suddenly change depth in the middle of your procedure. If you find yourself doing this, you might actually need to do more than one procedure, or consider whether you’re actually writing a process. This one is best explained by example:

WriteProcedures6

This certainly isn’t the worst example I could have picked, but it’s interesting all the same: a few of the steps here go into detail about some extra function that your product may or may not have (in yellow), while others are as simple as “open the velcro strap” (in blue). We also have process/procedure issues here, with procedures being numbers in order, and steps getting lowercase letters (in red). This is just confused by the photo references typed in red, and both angle brackets *and* square brackets being used. We also have a few stray bullets in one step. And having said all that, I’ll remind you that this is for a pair of boots. Admittedly, slightly more complicated boots than you’re wearing today, probably, but they’re just boots in the end. Also, I’m more than a little disturbed about the idea of “closure and locking of the foot” (in green).

Everyone knows what anthropomorphism is, right? Someone like to explain it? Yep, it’s applying human qualities to non-human things or animals. We do this a lot, especially to animals, but we also tend to do it to computers a lot.

I went online to find these ones, since I didn’t have any good examples in my stack of manuals. It seems to be something we do almost exclusively to computers rather than appliances, but we *really* do it a lot.

WriteProcedures7

I’ll give you a pro tip: computers don’t actually *think*. They might display things, they might take a while to process commands, but they definitely do not think.

Have to say, though, that going through manuals looking for anthropomorphism does make this one sound slightly creepier than the author intended …

WriteProcedures8

Which brings me to one of my favourite words, and it should be one of your favourites too: parallelism. When you’re writing fiction, you don’t want every paragraph or sentence to start with “Then”. When you’re writing procedures, though, it’s a good thing to have each step start with “click” or “type” or something like that. When you mix it up, it might sound more interesting, but it just becomes confusing. When faced with two statements that seem to be saying different things, users often think you want them to be doing something different. Every step should start with an action, and the same action should use the same verb. Use “click” for a mouse click, “type” for typing on the keyboard, “press” for a hardware button, etc.

WriteProcedures9

This manual almost gets it completely right. Three procedures here all need to start with the same three steps. But in one procedure, they write it using different terms. Is “tilting the motor head back” a different action to “raising the motor head”?

So, finally some takeaways:

The main elements of a procedure are:

  • Main heading (‘ing’ verb)
  • Concept
  • Before you begin
  • Warnings
  • Procedure sub-heading (infinitive ‘to’ verb)
  • Numbered steps
  • Reference info
  • Related topics

And the things you really need to remember when writing:

  • Mouse or keyboard, GUI or CLI? Stick to it!
  • Verb (or location) first
  • Active voice
  • Give instructions, not suggestions
  • Complete sentences
  • Plain English

I’ve also created a handout with these for you to print and hang up somewhere, which you can download here.


This article was originally given as a public tech talk at Red Hat Brisbane, in September 2012.

Share


Leave a comment

Because That’s The Way it’s Always Been Done Around Here

The writing industry has a schism. It’s not always obvious. We like to play it down. Some deny its very existence. But one day, you’ll be happily writing away in your new job, safe in the knowledge that you have a good grasp of spelling, comma placement, the use of industry terms and jargon, and can even confidently place a semi-colon in a position of value, when it hits you: are you a prescriptivist or a descriptivist? Suddenly your bubble collapses. The ship you were happily sailing on just moments ago collapses beneath you, and you’re cast away on an ocean of meta-questions. It’s all well and good to understand the basic tenets of grammar, but why do you understand those things, and in what way do you apply them? Are you putting a comma there because it makes historical and logical sense to put it there, or are you doing it just because that’s the way it’s always been done?

Most technical writers, those who have forged their career path through a combination of traditional university-level education in the field and into-the-deep-end, on-the-ground experience will give you a quick answer: Because the style guide says so.

Others, though, have had a somewhat more bumpy journey. They might have come from other fields such as journalism or creative writing, or they just might be the sort who overthinks this type of thing. Their answer will be more considered. They will describe the history of the word you have chosen, how its spelling and usage has changed over time, how the impact of technology has shaped its use, and how it fits into global trends.

Neither of these answers is wrong, although the two groups have argued (and probably will continue to argue) the point ad infinitum.

Prescriptivism is an easy answer, and the one that allows the writer to get on with things. They think “how do I handle this”, and there will be some guide – Chicago, AP, the Australian Government Style Guide, an internal document – that they can consult. They get their answer, they correct it in their work, they carry on. I have been this person.

Descriptivism is a more time-consuming method. In the absence of a font of all historical grammatical knowledge, it involves discovering historical usage, charting current usage, and predicting future usage. The answer, in many cases, is probably more ‘correct’ (or at least more considered), and the writer will certainly have a very long list of very good reasons for choosing the answer they do. It is the territory of the writer who needs to understand, not just do. I have, also, been this person.

In a recent conversation it was remarked to me that the speaker could not tell if I was in favour of neologisms or not. I argued that I am in favour of new words (and usage) entering the lexicon, but that I also feel it’s important to maintain an historical accuracy within our writing and grammar. It’s a somewhat contrary position to take, I agree. After all, new words and usage will not ever enter the lexicon unless they are used, surely? Dictionaries won’t include words just because they might be used next year. Fair point.

But, just as movies are not all science fiction, writing is not all technical, language is not all written, and audiences are not all university-educated, technically adept, native English speakers between 25 and 35. Writing needs to suit the audience, and different audiences have different expectations. This gives us a startling ability to watch language shift. Words can be used in a completely informal and slang way throughout most fiction and magazines, newspapers have historically been held to a higher standard of formality (although that is changing as the golden age of print takes hold), high-brow magazines and professional journals are expected to be quite formal, along with most technical documentation, and then academic papers hit the highest highs of formal language, with their stiff tone and impenetrable prose. But before new words are taken in at the beginning of that literary river to begin their long journey to towards the sea of obscurity, they must first be coined in the spring of neologism, and that occurs in the spoken word, and rarely in print. Take, as a simple example, the word “hello”. Originally used as an exclamation (and often historically cited as being used in hunts) or a way of gaining someone’s attention, it turned into a more formal greeting after Alexander Graham Bell’s initial plan of having people answer the telephone with ‘Ahoy’ fell through. ‘Hello’ eventually became the accepted standard, leading to call operators being referred to as ‘hello girls’ for decades, and the term itself becoming almost so banal as to not require a definition. It is interesting to note that, although ‘hello’ moved easily from almost-exclusive telephone use into a general greeting, the equivalent term  in Japanese ‘mushi mushi’ (????) has not, remaining a term used on the telephone only. Language is a living thing, and will change constantly, even in the face of criticism, denial, and plain old refusal to change.

Simply put: words begin in spoken slang, are gradually normalised through various print mediums, until time and usage turns them into stiff and ‘correct’ terms to be used until they fade into obscurity. Some fade into obscurity sooner than others, some have an amazing longevity with histories that fade into the fog of time. Technology has a tendency to speed the process up significantly, with terms such as ‘facetime’, ‘diskette’, and ‘webinar’ having had their brief golden age and are now (some would say thankfully) dying out again. It is also technology to blame for the re-purposing of words such as ‘login’, ‘instantiate’, and ‘friend’. And it is technology, I fear, that has spawned this entire debate between prescriptivism and descriptivism. It might seem strange to us now, where we are encouraged to be one or the other, but I believe that in times past, we have all been a little bit of both.

As a professional word-wrangler it is my job to understand my tools. I would expect a carpenter to fully understand saws: different blades, the angle of the teeth, the size and weight all make a difference to the final product (I imagine. I believe I sawed a piece of wood once, many years ago. These days I value my fingers too much!). I make it a point to understand my tools – words, and the grammar that binds them together – completely. As such, I enjoy taking the time to research the history of words and usage, and work out exactly why it is that I should (or shouldn’t) use them in the way that I do. To me, that’s essential knowledge that I require in order to do my job well.

On the other hand, I have a job to do. I need to get words on paper. The words I set to paper need to be accurate, they need to convey the right message, and they need to be able to be understood by my audience. They also need to be given to my readers when they need them, which means hitting deadlines. And that means that I don’t have always have the time to indulge my scholarly side and look up the history of every comma use, or fully analyse whether I should be using “shut down”, “shut-down”, or “shut down” in this particular instance. So I have to make a call: I spend time researching the important ones, the contentious ones, and the ones that will hopefully lead me to a greater understanding of other words. For the rest, I have my Chicago Manual of Style, our internal Word Usage Guide, and my dictionary. I lay my faith at the feet of the prescriptivists, but make sure I pay my tithe to the descriptivists, because who knows where all this is going to lead?

Share


Leave a comment

The Language of Change, and the Changing of Language

A conversation on the Australian Tech Writers mailing list prompted me to dig up these old blog posts from 2008 and repost them here. It was a short impromptu series of the changing face of language, and how we as wordsmiths deal with it:


Merriam-Webster – Bringing The Mondegreen To Linguistic Fanboys Everywhere

July 2008

Spotted this one on Slashdot today. Reading the comments, I came along quite a few that expressed what appears to be complete and utter dismay at the introduction of new words into the language. For example, this one:

“Even if you can guess what it means, it’s always good fun to pounce on neologisms and jargon and grill the user why they are using them instead of a more traditional word.”

And then there was this one:

“my old boss used to love these damn things and every time he’d say the word “webinar” a peice of me died a little inside”

It reminds me of a time I was driving around Brisbane with a friend, it was Christmas time, and I noted a sign in front of a church that stated something along the lines of “Christmass Services”. I made an offhand comment about the mispelling, and my friend pointed out that the origin of the word indicates that it should, indeed, be spelled “Christmass” (as it derived from the Mass for Christ). The main point of her comment though was the fact that language is an ever-changing and constantly evolving beast. Wordsmiths – myself included – are often very quick to point out that something is not a word, or is a neologism, or just isn’t right for some other reason.

We all use language in different ways every day – the language we use to speak to our friends is not the same as we use to speak to our children, or to authorities. The language that we use to write emails to our friends is different to the language that we use to write a complaint to the phone company. In my case, the language that I use to write technical documentation is different to the language I use to write fiction, and is different to the language I am using to write this blog post. The most interesting thing about that is the language that I use to do all those things has changed – as I’ve gotten older, as my opinions have changed, as my knowledge has increased, as my tastes have changed, and as I’ve come across new words.

I was working on the latest fiction project last night, writing very short snippets in first person for several different characters, and consciously trying to alter the ‘voice’ of each section to suit that character. Not as easy as it sounds, but I’m reasonably pleased with the results, so far.

Language, in all its forms, shifts and changes with attitude and society. While I’ve never considered Merriam-Webster to be authoritative, and I certainly wouldn’t rely on it for any of my work, at least we ought to give them credit for trying to document the language as it is used, rather than how it ‘ought’ to be. And for that reason alone, it has a place in the world.


New Words, Old Words

August 2008

Not so long ago, I wrote this. To summarise, it was about new words adopted into the English language by the Merriam-Webster dictionary, most of which had their genesis in online culture. So it was with great joy that I came across this article which outlines some of the words that the internet has succesfully killed. It’s a lovely piece of work, I suggest you read it. My very favourite is at the top of the list – “friend”. Once a word meaning ” someone you knew, had a personal relationship with, occasionally spoke to, and frequently drank beers with” it now, according to the article, means “someone who found your email address and typed it into Facebook and/or LinkedIN. You may have met said person at a conference once, and possibly even conversed with for 5 or more minutes”. Of course, my second favourite is in there too – “startup”. Once, it meant “a company with a novel idea, service, product, or technology, and a vision on how to build that company into a successful, profitable entity”. Now, it means “a college graduate and three friends who have an incremental idea, service, product, or technology, and a vision on how to build that company such that it gets acquired by Google, Microsoft, or Yahoo (in that order), preferably within 18 months for at least 9 figures.”

The article is tongue-in-cheek – and readily admits it – but there’s a whole lot of truth in there (albeit disguised nicely behind humour). Language is evolving, and the major vehicle for change is that thing that has become so pervasive in our lives – the internet – and the culture that goes with it. Not only have new words entered – “w00t” and “mondegreen” instantly spring to mind – but ‘old’ words have had their meanings modified to fit the new medium. I maintain that it’s not a bad thing, it’s progress (whatever definition you choose to use for ‘progress’). Sometimes it seems like backwards progress, but it is nevertheless the direction we are heading. Don’t like it? That’s OK – the new generation do. And when they’re all grown up and complaining about the “young ‘ens”, well, that’s OK too. Their kids will be busy picking up the slack by then.


All The World’s A Stage, And All The Men And Women Merely Players

August 2008


In what has become a somewhat impromptu series on the evolution of the English language, I just had to mention something I read whilst on holidays last weekend. I picked up Bill Bryson’s take on the life of Shakespeare whilst away. I’ve been interested in the great mystery of Shakespeare’s life for some time now. I own a copy of Nolan’s “Shakespeare’s Face” and have read numerous other accounts (or, more accurately, guesses) of his life and works. Add to this the fact that I have been wanting to start reading Bryson’s “A Short History of Nearly Everything”, and it was a fairly predictable attraction. Not incidentally, I’m intending to read his “The Mother Tongue” shortly too.

The book is quite short, and I finished it mere days after purchase – helped along by a few days in a warm climate with no pressing demands, I might add. It is written in true Bryson style, very conversational and light hearted, and he gives a lovely (or not so lovely, depending on your take on plague and wanton violence) picture of 16th century England, and Shakespeare’s somewhat unassuming – so far as we can tell – place in it.

However, my favourite part is this discussion of some of the many words that Shakespeare (allegedly) introduced into the English language:

And there was never a better time to delve for pleasure in language than the sixteenth century, when novelty blew through English like a spring breeze. Some twelve thousand words, a phenomenal number, entered the language between 1500 and 1650, about half of them still in use today, and old words were employed in ways that had not been tried before. Nouns became verbs and adverbs; adverbs became adjectives. Expressions that could not grammatically have existed before – such as “breathing one’s last” and “backing a horse”, both coined by Shakespeare – were suddenly popping up everywhere. Double superlatives and double negatives – “the most unkindest cut of all” – troubled no one and allowed an additional degree of emphasis that has since been lost.

Bryson goes on to mention the notorious variability of spelling known in early English society, noting this little gem –

Perhaps nothing speaks more eloquently of the variability of spelling in the age than the fact that a dictionary published in 1604, A Table Alphabeticall of Hard Words, spelled “words” two ways on the title page.

Of course, it just goes to show that the language has been evolving apace for many hundreds of years. Indeed, despite the naysayers it is happening much slower now than it was back in Shakespeare’s day. I can imagine that back then there were people (perhaps among the upper, educated, classes) who complained that artists such as he were mangling the language, and doing things the wrong way, although the attitude towards English was reasonably fluid then, thanks to Latin and French being considered ‘proper’. Surely, as time went on, and English took hold first in business and legal matters, and later in the sciences, that there have been people unwilling to accept change, even as it occurs around them. Nothing has changed in that respect, I imagine, it’s just that now they have access to the internet – and a world full of people reading their opinions. Hopefully, it won’t impede the progress overly. Much as I still cringe a little at “truthiness”, “coopetition” and “incentivise”, I am completely capable of embracing the words that I like – “blogosphere” is one of my favourites, along with “jumping the shark” and “backronym”. It’s only a matter of time before the language evolves to the point that our grandchildren will be almost incomprehensible, and Shakespeare’s scribblings will have taken another step towards total obscurity.

Share