On Writing, Tech, and Other Loquacities

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


2 Comments

Open Source Docs: the Good, the Bad, and the WTF?!

This is intended to be a bit of a light-hearted look at what can go so tragically (and sometimes hilariously) wrong with open source documentation. There is a bit of a point, though, and that is that I’d like to hopefully go through some reasons why you might need to consider having a real life tech writer work on your project, and how you can actually go about making that happen too. But first, on to the funny …

Open source documentation usually sits somewhere on a scale in between bad and awful. It’s not just open source, though. Bad documentation is everywhere. A lot of the time it’s confusing, but sometimes it can be downright dangerous.

The irony here of course is that they’re attempting to make the situation safer, but have managed to make it less safe by introducing a spelling mistake, and making the sentence so complicated that you need to read it several times before you understand what they’re trying to say. Which is different to what they’ve written. Of course, by the time you’ve read it and gotten the message, you’ve probably already driven off the road.

There are some truly wonderful writing-related quotes out there, so I thought I’d start out with this one. Some of you might have heard of this guy. His name is Jerrold David Freeman, and he uses the pen name David Gerrold. Under that name, he wrote an episode or two of a little known science-fiction show call Star Trek. David Gerrold, in turn, has his own pen name, Solomon Short, who wrote some appallingly bad fiction, apparently, but otherwise appears to be famous merely for a few pithy quotes, this being one of my personal favourites …

“I’m all in favour of keeping dangerous weapons out of the hands of fools. Let’s start with typewriters”.

Of course, the point here being that there really is some truly awful writing around, which is interesting when you consider how much of it he was responsible for.

And while we’re talking about dangerous weapons. I guess even a typewriter would be dangerous if you held it like this. But we’re supposed to be talking about open source docs here, so here’s one from a set of developer tools for PHP:

“There are four ways to start a session. Two are wrong”.

Because, just as with the chainsaw example, there’s nothing quite like telling people the wrong way to do things.

It leads me to another one that I come across all the time in open source docs. This one is a little more subtle, but it’s also much, much more prevalent, so I’ve got a few examples here, maybe you can spot the common theme:

“simply open konsole”.

Well, I guess that’s easy enough, if you can find it in the menu. Actually, if we’re talking KDE, if you can find the menu.

“The easiest way to do this is to simply”

Not only is it simple, it’s also easy! Yay us!

“Simply download the patch here:”

You have no idea how many times I’ve clicked a link like that either led to a page with a list of patches longer than a Tom Clancy novel, led to a page with no patches at all, or led to a 404.

“Simply type in the following commands”

Easy to type maybe, provided you know what all the switches do, understand all the parameters you’re setting, think in bash script, and have half a clue what you’re trying to achieve.

“Simply install the latest version”

Yeah, easy, why haven’t you finished that yet? And another one:

“Simply install the package”

Yup. Have you ever tried installing anything on Linux? If it’s not in the package manager, you’re on your own. And another one

“Simply install the package from their website”

As long as no one has moved it or changed it in the meantime. And my own personal favourite:

“<div class=”entry”> disappears entirely and <h3 class=”comments”> simply becomes <h3>”

Wow! Why didn’t I think of that! So simple!

Another quote, this one from Edward Gibbon. He said this many years before the concept of open source existed, but his words pretty much sum up many open source writers:

“Unprovided with original learning, unformed in the habits of thinking, unskilled in the arts of composition, I resolved to write a book”.

In open source, we all jump in and do what needs to be done, regardless and sometimes despite where our skills might lie. We’re all being forced to adapt to our environments in strange ways, stretch our skillsets, and do things we would never in normal circumstances do. So open source development tends to mean we all step in and do what needs to be done, but the main problem with that is the documentation isn’t recognised as “something that needs to be done” until fairly late in the piece. It’s at that point that someone realises that there’s a hole that needs filling up, and so some random person will be asked to step in and fill that gap.

Of course, the other problem that’s present in open source documentation is that of the amateur, and this doesn’t just apply to writing, either. People come to open source for a variety of reasons, but one of the main ones is to gain experience in their field, or to create or contribute to something that they can add to their portfolio. And I’m no stranger to this either, I frequently recommend contributing to an open source project as a good way for potential writers to start out. The problem with this of course is that in some projects, you end with a situation where the seasoned writers are burning out, getting run over by busses, or – heaven forbid – busy with actual real careers where they get paid real money and everything, and the majority of the grunt work is being done by people who – like Mr Gibbon – really didn’t know what they were doing. Not to say it’s a bad thing having new writers on a project, but like all the good things in life, it needs to be in balance. It’s no good having forty-seven amateurs and only one person who actually knows what’s going on, especially if it’s not a full time job for any of them.

In certain professions, it is natural to assume that the people practising them are skilled professionals. Doctor springs to mind, as does actor, and anything that involves sharp or particularly heavy machinery. Or pipe wrenches. Most people could at least have a good guess at what qualifications you would need to become a lawyer, a teacher, a plumber, a solar panel installation specialist, or a computer engineer.
But writing is still very much a dark art. And while technical writing certainly doesn’t have the mystique of, say, literary fiction or even a good horror writer, it is definitely considered a black box in many ways. And that, right there, is the problem. People don’t understand the skill required, the techniques employed, the training we have, even though we see product of writing work all the time. This, unfortunately, tends to mean that people figure it’s easy, and anyone could do it.

So you end up with a situation where the documentation becomes something of a hot potato. Everyone knows it needs to be done, nobody wants to do it, eventually it lands on the one person who was stupid enough to admit to either knowing a typesetting language, having some felicity with a word processor, or once having had a job where they sat next to someone who had to do some writing.

Basically, we’re surrounded every day – not just in open source – by stuff written by people who barely know how to string a sentence together. And it’s not just about choosing the right ‘your’ either. It’s also about organising the information in a way that makes it … well, informational.

The next quote is from one of my favourite authors. His name was Eric Blair, but he was better known as George Orwell. He’s most famous for giving us the notion of Big Brother, but he also left us with some fabulous writing advice. His most famous writing advice was given in 1946 in the form of an essay called “Politics and the English Language”, which is where this quote also comes from:

“In certain kinds of writing … it is normal to come across long passages which are almost completely lacking in meaning.”

And while this may well have been true in 1946, unfortunately no one must have been listening, because it’s only gotten worse.

This is from a ZDNet article that was written about a product I’m currently writing for, it says:

“CloudForms, which is based upon the company-sponsored DeltaCloud project that is now part of Apache– offer sophisticated resource management, application deployment services and Infrastructure-as a Service offerings that help IT adminstrators implement private and hybrid clouds”.

It doesn’t end there, they go on to say:

“The platform consists of a cloud engine for high level automation and abstraction services across multiple virtualization hypervisors and virtualized clusters, an application engine and system engine for comprehensive application lifecycle management across multiple cloud providers and various Infrastucture -as-a-Service offerings including storage, messaging and high availability services”.

Basically, that is 88 words that are completely devoid of meaning.

I’ve left the typos in for your own amusement.

Which brings me neatly to my next piece of wisdom, this one from the web comic author Randy Milholland (Something Positive), who said that

“Typos are very important to all written form. It gives the reader something to look for so they aren’t distracted by the total lack of content in your writing.”

Which could easily explain most of the Register’s articles these days.

So let’s explore this problem a little more. In order to solve a problem, though, we need to define exactly what the problem is, and that’s where open source makes it difficult, because open source encompasses much more than just Linux, and one solution is never going to apply in all situations. So, let’s take a look at the issues. There are of course two broad types of open source project:

There’s the cathedral type, where you have some piece of software that’s been developed internally by some company and then released as open source, or the flip side of that is the RHEL model, where they branch an existing project, which is then worked on internally and released to the public again.

Then you have the bazaar type, which is what many of us tend to think of automatically when we say “open source project”. This is where some teenaged genius has a brilliant idea and then somehow convinces everyone else it’s brilliant and they should contribute to it as well.

So of course, I can go on at length about how documentation is handled in the cathedral version. In Red Hat’s case, of course, we hire people, train them, and then get them to pump out documentation. For the most part, what they pump out is pretty good, but that’s to be expected when you’re putting effort in to finding and hiring the people best suited for the job.

Another interesting one that’s more or less in the cathedral category is Libre Office. They’re created by a seemingly endless stream of volunteers, but are extremely susceptible to the newbie problem. There are one or two community elders who know where everything is and what needs to be done next, and there’s a steady flow of people who drift in, do a few things, and then drift out again. It works, oddly enough, and if you’ve ever used Libre Office documentation then you would know that what they pump out is pretty high quality.

So let’s move into the bazaar-style projects. Of course one of the best ones for documentation is Gimp. Their user manual is a thing of wonder, and they also have an amazing array of tutorials. I haven’t had much to do with the gimp docs community, but as far as I know they have a relatively tight knit group of core documenters, which says a lot about how having a core group of experienced writers can really help your overall documentation.

And it’s also interesting to contrast Gimp to Inkscape. Inkscape has a really robust community of contributors, but they haven’t had the documentation focus that Gimp has.  For some time they’ve had a fairly robust users manual over at the Floss Manuals site, though, so perhaps they just haven’t seen the need to expend energy on doing it within the project.

Of course, it’s important to remember when we’re talking about Gimp and Inkscape though that in terms of bazaar-style open source projects, they really are the cream of the crop. To get a more realistic view, let’s look at a little tool I was trying to get working not so long ago called ‘recordmydesktop’. This is their documentation page, so the fact that they have one is a good start. You might notice the last time it was updated though. 2008 in the case of the FAQ, and 2007 in the case of the manual. I won’t get started on the manual itself, because we only have forty minutes.

So we’ve more or less ascertained that most documentation sucks, and open source documentation tends to suck slightly harder than the rest. The next question then is, what are we going to do about it. If you have lots of money, the answer is easy … pay a professional writer to do it. Depending on who you get, and how much money you give them, you should end up with something pretty reasonable. Hopefully.

If you’re in this happy situation, then you need to go looking for someone who is a writer first and a technology nut second. There’s a fairly common thought, especially amongst the IT crowd, that you can’t document a product unless you have a full understanding of the technology behind it, and possibly several decades of experience in using it. Well, I’d like to stand up here today as living proof that that statement is a lie. Complete and utter fiction. The skills of a professional technical writer include being able to wade into a product they’ve never seen or used before, and be able to document it fully. That’s because professional writers are trained in the art of audience analysis.  They approach the product in the same way as a user, which means they are much closer to the learning curve that your users will be going through, which ultimately helps them document it.

Let’s have a car analogy! Imagine you’re a mechanic, and someone has asked you to describe a car to them. There’s a reasonable chance that you’re going to start off describing how the car converts fuel to energy, which drives the engine. But if that person has never seen a car before, what they really need to know is that it is a box with wheels that can move people from place to place, before they understand catalytic conversion.

Of course, money ain’t always easy to come by, especially if you’re in the open source space. But that’s not to say that you can’t get writers to write for free. The good thing about writers is that they tend to have this undeniable drive to … well … write. It’s that drive that creates such wonderful things as NaNoWriMo. National Novel Writing Month – or NaNoWriMo – is where people sign up to write 50,000 words in 30 days. For free! I’m sure many of you think this is completely nuts, and I’m sure you’re probably right. But there’s lessons to be learned here, too.

The biggest lesson we can take away from things like NaNoWriMo is that if you give writers an attractive writing environment, they will come to write for you simply because it seems like it might be fun to do. And so this means you might need to put a little bit of thought into how you project is going to be documented, in order to be able to make that authoring environment as attractive as possible.

Briefly, I’d like to hark back to what I said earlier about Red Hat. Red Hat have about 90 people in the documentation group now, with more than half of them being writers, and the rest translators. And we haven’t slowed down hiring (Incidentally, if you want a job …). Why is it we can find so many writers? Well, a lot of it has to do with the environment we offer potential new writers. Can you see a pattern emerging here?

So here’s my list of great writing environment factors, whether you’re paying your writers or not:

Give writers freedom in the tools they use. This allows experienced writers to use tools they’re familiar with, and to adjust and improve the way they work with your documentation. If you have always produced documentation in a word processor, and you have a great writer come in and want to start working in Docbook XML or LaTeX, then let them. If they’re experienced enough to know what that is and how to make the change, they’re worth being flexible for.

On the other hand, provide a simple structure and process for producing documentation. Don’t make people jump through hoops to contribute to the docs. This helps new writers on the project get up and running quickly, and it helps people who are not proven writers get started. We all know how important it is for our contributors to be able to submit their first patch quickly and fairly easily, so that they get that hit of satisfaction and stick around. It’s exactly the same for writers. Make it easy for them to do quick tasks like fixing spelling and grammar mistakes, and maybe have an up to date list of smaller projects that need doing, ready for when new people sign up to the mailing list.

 A robust documentation team will pick up many, many bugs for you. Within Red Hat, a large proportion of the bugs found in our software before it’s released, is found by the documentation group. And that’s aside from the other positive benefits that good documentation can bring to a project, including the single biggest factor, which is decreasing support calls. Make sure you acknowledge the work the documentation team does. Make sure that whenever you mention contributors or volunteers, that those on the docs team are mentioned as well. Don’t include them as an afterthought, or as a generic group called “the documentation team”. Name them! Make sure they know you understand and appreciate that the work they have contributed is just as important as the work contributed by developers. And this works to attract more writers too: if people see that writers are acknowledged and appreciated in a project, they’re more likely to feel as though they too will be rewarded by joining.

Recognise writers as experts in their field. If they tell you that something doesn’t read well, or they recommend that you choose a different way of expressing something, listen to them as you would another developer. You don’t have to agree with them every time, because that’s not the way the world works, but recognise that where you know how to sling code, they know how to sling words. And if they’re coming to you and saying that your documentation sucks, perhaps you should give them an opportunity to step up and make it better.

And finally, ensure you have a positive and welcoming community. I know this isn’t easy, but it’s probably the single biggest recommendation I can make. As a job classification, writing – even highly technical writing – does not suffer from the same gender imbalance as software development. Roughly half of your potential writers will be women, and roughly half will be from a background other than white and north American. And it won’t necessarily be the same half. If you don’t have a code of conduct, and if you don’t have a community that actively welcomes and supports women and minorities, then you are cutting down your pool of potential writers by well over half. And I don’t know about you, but that just seems dumb to me.

So I’m going to leave you with some final words of wisdom from the Polish writer Stanis?aw Jerzy Lec: “Advice to writers: sometimes you just have to stop writing. Even before you begin”.


This blog post was originally a talk given at the 2011 Open Source Developers’ Conference in Canberra on 16 November, 2011. Video of this talk is now up on my videos page.

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


1 Comment

Open Source Documentation in Four Easy Steps (and one slightly more difficult one)

At Red Hat, we have a content services department that is about sixty people strong. Even though the department is pretty big these days, back when I started with the company, we were still trying to work out the best way to run a successful enterprise-level documentation team. What that means is that I have been involved in some of the big discussions that we have had over time about what processes we needed to get in place in order to allow us to produce the massive amounts of documentation we required as our product offerings grew. As a department, we grew very big, very fast, and our processes needed to be flexible enough to accommodate the large number of new hires we had, and still have, coming in, but robust enough to be valuable and reliable. They also need to fit in well with the engineering practices in place in the company, and the tools that our development teams use and are familiar with. Of course the other really important factor was that we had to be open. We wanted to use completely open tools to produce our docs, but we also needed to be able to work with community teams, such as the Fedora group.

Like many documentation groups, at Red Hat we use a five-phase waterfall model to produce documentation. It’s based on the ever-popular JoAnn Hackos method: starting with planning, the content specification, then writing and editing, translation and production, and then a retrospective review. At Red Hat at the moment we’re at a place where our development teams are increasingly using Agile-style development models to produce software, and that means the pressure has been on us to develop in a less rigid way than the old waterfall model has been allowing us to do. Also, it’s no secret that the online world is changing, and people now expect to be able to interact with information at a much deeper level than ever before. They don’t want to be presented with static, hard-copy books any more. They want dynamic, interactive, usable, and above all useful documentation.

In order to be able to work out what kind of model we needed to use, we needed to go back to basics. All technology is about solving problems. Back when we were sitting around in caves, we had a problem: there was all this food running around outside, but we didn’t have a way to get it to stop running around, so we invented a club and solved the problem. Since then, we’ve used technology to solve all sorts of problems: horses were sometimes problematic to control, and they didn’t go very fast, so we invented cars. The hard wheels used on early cars weren’t very comfortable, and when they broke they really broke, so we invented pneumatic tyres. We also had problems being able to see in the dark so we invented electric light, being able to go to the toilet when it was raining or cold so we invented indoor plumbing, being able to send messages to people on the other side of the country so we invented the telephone, or on the other side of the world so we invented email.

Even these really technological things that we find ourselves documenting now, are all solutions to problems. One of the first things you need to be aware of when you’re writing documentation is what problem your users have. If you can’t describe the problem in one or two sentences, then you don’t understand it well enough, and you need to keep researching. Because if you keep going, all you’re going to end up with is hollow marketing spin. That’s how we end up with documentation that talks about “leveraging synergies”: words that sound great, but have no meaning.

So at Red Hat we came up with a fairly simple model, and that is that documentation needs to be able to be boiled down to three things:

  • Describing the problem
  • Solving the problem
  • Giving any additional information

Anyone who has done any work with DITA would understand that what I’m really talking about here is:

  • Concept
  • Task
  • Reference

 

So we’ve more or less said that DITA is where we need to go next. But we didn’t want to completely restructure the tools we were using. We have a fairly large people investment in our tools. The main tool we use is Publican, which was developed by an engineer in our Brisbane office. It uses Docbook XML and gives us a command line interface that we can use to create new blank books, apply corporate formatting, and it integrates into our internal packaging system so we can create all these different formats for our books – HTML, PDF, and ePUB on the website, and we can also create RPM packages and man pages to package in with software. We combine Publican with SVN to give us a complete CMS, in short.

We looked at DITA and DITA-OT, the DITA Open Toolkit. We realized two things: first of all, it would take a significant amount of work for us to bring an open DITA toolchain to the level of maturity and system integration of our existing Docbook toolchain. Secondly, we wouldn’t get the really significant benefits of topic-based authoring without a Component Content Management System – a CMS that manages content at a very granular level. Putting those two things together made it clear that if we changed to DITA all in one hit, it would take us significant time and energy just to get back to where we already were with a mature open source complete tool chain. So we decided to take an evolutionary, rather than revolutionary approach. It’s a much more open source approach: to re-purpose something that you already have, add a script here, a small command-line tool there, release early, release often, and let the user community guide the development, rather than trying to design and implement some grand system in a distant (and expensive) future.

What we needed was something that worked in a similar manner to DITA, gave us content re-use and all that good stuff, but that would work with our existing Docbook XML and Publican tools. The first thing we did was to start creating topics in Docbook, using Docbook syntax, and a command line tool that we called the “Topic Tool”. This was a really simple command line tool that allowed us to write XML snippets (or ‘topics’), and save them in SVN. We used an extensible template model, where the topic tool retrieves a Docbook template from a central repository to match the topic type you specify. That way we can create new topic types, and even modify the Docbook syntax of existing topic types, without changing the tool on users’ machines. That was an important decision, and a major part of the evolutionary “Release, Review, Refine” approach we wanted to use. Over time we did change the Docbook syntax of the basic topic types and create new topic types, validating the open source maxim “plan to throw the first one away”.

The basic workflow with the Topic Tool is like this: you tell the tool which topic type you want, and it will then download the template and prefill some information for you. You can then edit the topic in a text editor, and import it back into the repository. It’s then possible to view your topic from the repo directly, which means anyone can now see it and use it. We then include those snippets into any book you want using an xi:include, build the book as normal with Publican, and voila! we have a book with content reuse. So that was pretty awesome, and if you read any of our Virtualisation documentation you’ll probably not know it, but that’s all based on topics and maintained using the topic tool.

Of course, once we got to about 300 topics in the topic tool, we started to notice that we have another problem, we were having trouble locating topics within the repository. This made us realise that what we needed was a better way to organise it all, so we wrapped a neat interface around Topic Tool using Open Grok. OpenGrok is designed for software engineers to search source code repositories, so it worked well for what we were trying to do. This is where the open source ecosystem came into its own all over again – there are a million off-the-shelf components and projects that you can choose from to build your own system. In the end we had a web-based search tool that was pretty basic, but did the job.

Content reuse is an obvious application of topic-based authoring, but by this stage, we’d started to realise something even more exciting. Our definition of a topic is a unit of information with a single subject – that means that it talks about one thing, and one thing only – and that has a single information role: that is, it’s a concept, a task, or a reference. If we gave three topics – a concept, a task, and a reference – to a robot, along with a rule describing the “explain, answer, extra info” pattern, and some kind of graphical template, that robot can assemble those topics into meaningful and useful output for an end user. What we wanted to do was to automate this process.

When humans assemble content into a book, they are making decisions. What aspects of the information are their decisions based on, and what rules are they consciously or unconsciously using? That was what we wanted to create: A system that would allow us to store metadata about a topic, and use rules to automate assembly on a scale that we just couldn’t do by hand-coding.

So we developed a system that we call Skynet, which allows us to dynamically sort and locate topics. Select the topics you want, and Skynet will download the code that presents those topics in a consumable way. Of course, we started dreaming big after all this. We’ve started thinking about moving away from the documentation-as-a-book paradigm, and started considering “Documentation 2.0”. Why not include comment fields on our documentation, that will allow our reviewers – quality engineers, subject matter experts, editors, and the like to make comments directly in the book rather than creating a separate list? And why not offer that functionality to our users as well? What if we had the equivalent of a Facebook ‘like’ button? Users could ‘like’ sections that they found useful, or leave comments saying “when I tried to follow these instructions, X happened” or “this seems to be missing a step” or the like. If we break away from the book model, we start to be able to think about documentation as something that our users can interac with. We could have popular topics bubble up to the top of a list, or divide books into audiences, and present the information for each audience differently, giving them a tab to click to see the information in various ways. We could implement something similar to the Amazon “customers who bought this also bought this” and present similar topics to our readers. Using single-sourced content, and content reuse, through a system like Skynet, is going to allow us to move into these more innovative delivery methods.

The team working on the Skynet project have 110% discoverability as one of their goals, to quote the team leader: “the documentation finds you”. In other words, when you’re working on something, and you get stuck, the documentation is there at a click or a glance, ready for you to interact with it. Of course, I’m sure some of you are saying “Help” right now, and yes, I agree with you. That is something else we’re talking about, and something that Skynet will enable us to do. Skynet pushes out XML now, and of course there’s plenty we can do with that as it is, but we can also extend it to push out all manner of things, including Mallard for Gnome Help.

So let’s take this conversation back to processes. All this dreaming is fantastic, but at some point we still have to actually do the hard work. Without a solid process, and a great set of standards, we’re not going to be able to get there. We’re doing a lot of internal testing, and we’re dipping our toes in the water with the topic tool and with Skynet. So far, we’ve been able to slip these in to our existing standards, but that’s not going to last for long. With a paradigm shift as big as this, everything is going to have to change, and that includes the way we go about producing our documentation. We need to be organised, we need to make sure what we do is repeatable, and we need to maintain our high standards of quality and accuracy in our documentation. Most of all, though, we need to maintain and even increase our focus on the customer. These changes come about not because we got bored with doing things the old way, but because we believe it’s a better way to serve our audience. Never, ever forget who you’re writing for, it’s those poor sods out there with their problems that they’re trying to solve. Our goal is to give them the tools they need to solve them.

So, to recap:

One of the main things that we have learned is that process is king. If you don’t have a solid process for producing documentation, then you’re going to find yourself floundering at every point along the way. You’re going to end up with documentation that doesn’t cover what it needs to cover, isn’t accurate or well-written, and doesn’t get out on time. Without a plan for how you’re going to tackle the project from end to end, then you’re not going to succeed. It’s that simple.

The second thing is about tools. You need to decide ahead of time what tools you are going to need during the project, and make sure you have them ready and up and running before you start. It’s horrible to get halfway through writing and find out that one of your writers doesn’t understand how to use a semi-colon. It’s even worse if you get halfway through and realise that one of your writers doesn’t understand Docbook XML, or whatever authoring tool you’re using.

While we’re talking about tools, it’s important to keep it open everywhere you can. This can seem counter-intuitive to those of you who have worked in big companies, but being open doesn’t mean giving away business secrets, or exposing your competitive advantage. I think Red Hat of all companies really proves that the openness can co-exist with secure business practices.

Part of keeping it open is about keeping it real. The people behind your processes, the people doing the actual work day in and day out: they’re real people. They’re real people, with real lives, and real families. You need to be able to work with people, and ensure that the loss of one person isn’t going to make the whole project tumble. The other thing you need to remember is that your readers are real people as well, you need to make sure that you’re giving your readers something useful, and something that they will get value out of.

And finally, I want to remind you about reviews. We all understand the importance of reviewing our writing for correctness, and reviewing our projects to make sure we can learn from our mistakes. You need to extend reviews to the documentation process itself, as well. Never be afraid to change things around. Just because it worked last time doesn’t mean it’s going to work next time. And just because it’s worked in the past, doesn’t mean it’s the best way to do it in the future.


This post was originally a talk given at the Open Help Conference in Cincinnati Ohio, on 5 June 2011.

The slide deck is available on Slideshare: Open Source Documentation in Four Easy Steps (and one slightly more difficult one)

You can also download this article as a PDF file: FourEasySteps


Share


Leave a comment

Sssh! Sneak Preview!

Don’t tell anyone I told you, but here’s my slide deck for the presentation I’m giving in Cincinnati this weekend at the Open Help Conference

Not sure if there’ll be recording on the day or not, but I’ll get some more details up here afterwards, either in the form of video or an article.

See you soon, America!

Share


3 Comments

The Grass is Greener on The Open Side

The Grass is Greener on the Open Side

Now, I know what you’re thinking. You’re thinking, “Oh my, here we go again. Another open source advocate banging on about freedom”. Well, yeah, I have to admit to at least a little bit of truth in that. Open source advocates do like to talk about morals, and they do like to say things about open source being ‘good for society’ and how it’s the ‘way of the future’. Most of all, though, open source advocates like to bang on a lot about ‘freedom’. But I’m not your average open source advocate. Every tech writer has their favourite program to use, and in many cases you don’t get a choice about which one that is. I’m not going to tell you that you shouldn’t be using those programs, and I’m not going to tell you to go to your boss and tell them that you’re not going to be using those freedom-hating platforms any more. It’s just not practical. I will tell you to use whatever works for you. If there is a program that you use that ticks all your boxes – that does absolutely everything you need it to do, then by all means go ahead and use it. All I want you to do is to be aware of the alternatives, and to understand the differences between them. That way, you’re making an informed choice about the software you use, and the way you interact with technology.

Freedom, and how it relates to beer

So, I said I wasn’t going to bang on about freedom, but I do need to mention it, if only to straighten out some of the terms I’ll be using. Freedom gets mentioned a lot when discussing open source software, and thanks to Wikileaks there are a lot of nonsense phrases doing the rounds right now like “information wants to be free”. I would like to explain what we actually mean when we talk about open source software being ‘free’. As I’m sure you’re all painfully aware, English can be a bit confusing sometimes, and we quite frequently come across words that have two or three different meanings, depending on the context it’s used in. The English word ‘free’ is a perfect example. We can steal two words from the Romance languages to describe the different ways we use ‘free’ in English. First of all, a word I’m sure you all know and love, is ‘gratis’. The word ‘gratis’ means free of charge, or without cost. The other word is ‘libre’ which means the state of being free, or of having liberty. There’s a much easier way to illustrate this concept though.

We all know that the best beer is the beer you don’t have to pay for. That is, it’s beer that is ‘gratis’, or free of charge. We can refer to software as being ‘free as in beer’ when we mean that it doesn’t cost any money to use. This is the type of ‘free’ that is being used when we discuss freeware, which you’ve probably all come across before. Freeware is free as in beer, but it has its catch: you still need to read and agree to the end user license agreement in order to use it, and you won’t be allowed to change the way the program works, or create any add-ons or extras, such as documentation or translations. In many cases, freeware can only be installed on personal networks, not business ones, and there are quite often restrictions on how easy it is to share the program too.

When we talk about the ‘libre’ sense of free, we say ‘free as in freedom’ or ‘free as in speech’. Essentially, when we talk about freedom with open source software, this is the freedom we mean. It’s the freedom to see the nuts and bolts of the software you’re using, the freedom to make changes and share them with your friends, the freedom to take the code and use it in your own project, and the freedom to suggest and submit changes to the code itself, or the stuff that wraps around the program, like the documentation. It is also possible to have software that is free as in freedom, but isn’t free as in beer, too.

Have you got a licence for that thing?

So before we move on there’s one other term I’d like to straighten out: pirates. My entire network at home was set up using free software – that’s free as in beer, it didn’t cost me a cent. However, I’m not a pirate (and that’s not just because I don’t have a wooden leg and a parrot). Every piece of software I use in my home network is open source and was obtained perfectly legally.

This is because the free-as-in-freedom and the free-as-in-beer is written into the license agreement for the software I use. You’re probably familiar with the End User License Agreement (EULA). That’s the bit that you have to agree to when you install closed-source software. It’s usually a big long chunk of text, all written in legalese, and we all ignore it and hit “I agree” to continue. Open source software doesn’t use a EULA, but it does have a license. The license works in more or less the same way as a EULA, except instead of saying “You may not sell, license or distribute copies of the software” it says something more like “you can use this software free of charge, as long as you keep it that way”. In other words, if I wanted to pay for it, or I wanted to sell it to my friends, I would be breaking the agreement, in the same way that giving away copies of Microsoft Office for free would be breaking the EULA. There are lots of different open source licenses, but they all work in much the same way, with only minor differences between them. The main one is the GNU General Public License, which is referred to as the GPL. The main restriction on the GPL is that whatever you do with the code, it needs to include a copy of the GPL with it. And that’s really as scary as it gets. I could go on at length about licensing, but there’s probably another whole article in there, so let’s move along.

Decision time!

Consider you’re in the market for a new bit of software. Often your purchase decision will come down to features, and if one option has the features you need and the other one doesn’t, then by all means go ahead and install the software that has all the bells and whistles you require. Provided you agree to the terms of the license or the EULA, and you pay whatever is requested, then there’s no problem. But what about when the features are equal, and the differences come down to licenses and cost? Most of the big name software will cost you money in some form or another for the full version. After you’ve paid your money the product is yours though, right? Wrong. The software company can decide to change the software whenever they want. You would have all seen this happen on your Windows machines. You agreed to a EULA when you installed it, but Windows gets new updates every other day. Got any idea what’s in those updates? No, nor do most people. We need to trust that the big software companies are going to do right by us, and in most cases that’s not difficult to do. They’re big companies with millions of users, and if they tried anything nasty, we’d probably know about it. So that’s a risk most of us are perfectly willing to take.

>So you’ve paid your money, you’ve got your software, and you’ve been happily working away with it for a while. Then someone sends you a file that you can’t open, because it was created with a newer version of the software. All of a sudden, you realise that your old version doesn’t have the features that the new version has got. So what do you do? You have to upgrade. Which costs more again. Once again, you click through the EULA, agree to it, pay your money, and you’re off again. You’re probably very familiar with this process.

Now, what happens if you don’t like something about the program, or if you discover a bug in the program – something that doesn’t work properly? For the most part, you probably shrug it off. There’s not much you can do about it. What about the documentation? We’ve all come across laughably bad documentation, hopefully you weren’t the author of too much of it. What happens when the documentation for your piece of software doesn’t describe things properly? Or doesn’t include information you need? Have you ever thought “Gee, I could write that so much better”. If you’re multi-lingual, have you ever wished that a company would provide documentation in a different language? Have you ever wanted to create a guide that covers a situation you use every day, and you think others would find it useful too? You can’t do any of that stuff with closed source software, because the EULA specifically forbids it. The only way to be able to make those changes would be to go and get a job at Adobe or Microsoft. And while I’m sure we’d all love to land a position like that, unfortunately for most of us it’s not horribly likely.

So let’s look at the alternative. Most open source software will cost you nothing, it’s free as in beer as well as free as in freedom. You would go to the website, pick the version you want, and you’re off. If you need help, you can check out the embedded help, or the official documentation on the site, just like with any other program. And if you don’t like either of those options, there are heaps of other places to get help: wikis, forums, chat channels, numerous blogs and websites. You could also go to an open-source manual website, like flossmanuals.net and find out if someone else has written a full guide. And what about problems or bugs? The first thing to do is to search the web, it’s possible that someone else has come across the issue and has already found a solution. If not, then get in contact with the developers – all open source projects will have a number of ways to do this – and let them know about it. They’ll probably ask you for some more details about the problem so that they can get it fixed, and then they’ll go right ahead and fix it for you.

The other fun part is if you think you have something to add. If you’re a programmer, and you’d like to write a new feature, or fix a bug, you can do that. If you’re a writer, and you want to improve the documentation, or you want to do a translation, then you can do that too. In those cases, you will usually be welcomed with open arms and given everything you need to get started. And that’s because open source software is not developed by a group of paid engineers in an office block, but by people like you and me. It’s created by a community, and anyone who wants to be a part of that community and work to improving the software they’re using will always be welcome. Of course, you don’t have to contribute to a project, though, if you don’t want to. You can also just download and use it, just as you would with any other software.

Arguments, naturally

Of course there are arguments both for and against open and closed-source software. Most of them on both sides are reasonably valid. One of the main ones is that closed source stuff is usually more stable than open source, because they have a room full of developers who are paid to fix bugs and write features. This is interesting, because in some cases it’s true. But to be a fair comparison, you can’t really compare the stability of Word against the stability of a project that was created by two guys in their garage for their three friends to use. If you want to compare them fairly, compare the stability of Microsoft Word to the stability of Open Office, which is an open source project by Oracle and is supported by IBM, amongst others, and has been around for over 10 years. Neither of these projects are likely to go away any time soon. The other side of the coin is the little software development groups. Anyone can produce software and sell it, and if those little shops go bust you end up with an unsupported product. That doesn’t change whether it’s open or closed source. The difference is that with open source, because the code is available to anyone who wants to look at it, there’s at least a chance that someone at some point will pick up the code and have another bash at it. That’s never going to happen with closed source projects, simply because the licensing doesn’t allow it to happen.

I’m still not sold

The good news is that you don’t need to be totally sold on either open or closed source software. You don’t have to go totally one way or the other. Because open source software is free to use, and easy to get, you can go ahead and download any number of programs, just to see if you like them. And if you feel like making a contribution to the program, or joining the community around your favourite program, then go ahead and do that too. The great part is that you can install and use open source software anywhere you want, and use closed source software in exactly the same way. They will happily co-exist on the same system.

It’s not just about the freedom

I said right at the beginning that a lot of open source advocates bang on a lot about freedom, and I guess that in a lot of ways they’re right. Freedom really is a big part of open source, and explains a lot of why it’s awesome. But I think there’s something more to it. It’s not just about the freedom, it has a lot more to do with the community. Whenever you get group of people together with a common goal in mind, they can achieve just about anything. When the goal of that group is freedom, then I think that the world can really only become a better place because of it.

—————————————————–

This article was originally a web seminar for the Society of Technical Communicators. Since then, I have also presented it for the Canberra Society of Editors. It was longer as a speech, but had fewer funny bits.

—————————————————–

A shortened version of this article was published in Words: A Quarterly Bulletin for Technical Writers and Communicators. Volume 3, Issue 2: May 2011

—————————————————–

Share


Leave a comment

Society of Editors Playing in the Grass

Some time ago, I gave a web seminar for the Society of Technical Communicators (STC) in the US, which was an interesting experience. Considering it occurred at 4am local time, I’m not entirely certain I was at my best, but luckily I’ve been given the opportunity to repeat the talk at a more reasonable time. The Canberra Society of Editors also welcomes the ACT branch of the Australian Society of Technical Communicators (ASTC) to their meetings every month, and through this happy alliance, I will be presenting The Grass is Greener on the Open Side on 27 April at 6:30pm, at the Australian National University.

I’m constantly surprised with how closed the technical communicator’s world can be. In an industry where Adobe and Madcap rule the roost, if you mention that you work in open source, or use open source tools, people tend to nod mutely. Either they have no idea what ‘open source’ actually is, or they have no idea what working with open source tools might actually entail. And so this talk was born. It is intended to be treated as Open Source 101 for technical communicators, essentially.

And of course, if you can make it along, I’d love to see you!

Share


Leave a comment

Louisa Lawson and The Digitise The Dawn Project

Louisa Albury was born in 1848 in Mudgee, the second of twelve children. Although she was offered a position as ‘pupil teacher’ at school, she was encouraged by her parents to leave school in order to look after her younger siblings. It was a fairly common thing to happen to eldest girls at the time, but judging by Louisa’s later life, it seems that she regretted it most severely. And who can blame her? She married Niels Hertzberg Larsen (who called himself Peter) in 1866 at the tender age of eighteen, and they later Anglicised their surname to Lawson. Peter, for good or bad, spent much of his time away at the goldfields, and left Louisa at home to look after their brood of five children alone. Eventually, his absences became longer and more frequent, and by the time Louisa moved with her children to Sydney in 1883, the marriage was all but over. Left alone with five children to support, and with very little and sporadic financial assistance from Peter, she turned her hand first to sewing and washing to earn money. She also took in boarders from time to time. In 1887, she took the opportunity to purchase The Republican newspaper, a paper about which I’ve been almost completely unable to find information on, sadly. The one thing I have learned, though, is that it (apparently) “called for all Australians to unite under ‘the flag of a Federated Australia, the Great Republic of the Southern Seas'”[0]. By all accounts, it didn’t last long though, and ceased production the following year, in 1888. But Louisa’a political leanings were very much beginning to show.

Apparently bitten by the publishing bug, and probably eager to continue publishing her own essays and works of poetry, she started publishing a magazine called The Dawn in 1888. It was printed as “A Journal for Australian Women” and “publicize women’s wrongs, fight their battles and sue for their suffrage”[1]. It was the first newspaper printed in Australia that dealt with issues of feminism and suffrage, and is considered perhaps the single most important factor in the beginning of the suffragette movement in Australia. Shortly after The Dawn‘s inception, Louisa’s husband Peter died, leaving her with a large inheritance, which was immediately spent on improving the printing press and increasing the circulation of the magazine. She also hired ten staff, all of whom were women. The NSW Typographical Association did not accept female members at the time, and took exception to the fact that a magazine could be edited, printed, and circulated only by women. They took up arms against Louisa and the magazine and encouraged advertisers to boycott The Dawn and reportedly harassed the women on site.

As evidence of Louisa’s strength, she did not let this discourage her, and in 1889, she began running meetings at the Dawn offices which became known as The Dawn Club. The Club discussed issues relating to the “evil laws” made by men, and encouraged women to infiltrate male-dominated arenas such as debating clubs, and Louisa herself became the first female member of the board of management of the Sydney Mechanics’ School of Arts.
Rubbish Paragraph
The Womanhood Suffrage League of NSW began in 1891 and, hardly surprisingly, Louisa was elected to its council. She offered the Dawn offices and printing press for the League to use for meetings and pamphlets free of charge, and this remained the case until the League’s demise, despite the fact that Louisa herself withdrew from the council in 1893 after an ill-documented dispute.
Rubbish Paragraph
By the time women were given the vote in 1902, Louisa was starting to slow down. In 1900, she had a fall from a tram and was badly injured, although she was politically active again in 1902 itself, when she was introduced to the Australia parliament as “The Mother of Suffrage in New South Wales”[2]. During the early 1900’s she took several extended ‘rest’ periods from her campaigning and the magazine. She was 54, not old by our modern standards, but perfectly elderly by the standards of the day, and she had worked hard both physically and mentally all her life.

With the coming of the women’s vote, Louisa aged and so, sadly, did The Dawn. The columns grew fewer and less fervent, the advertisers gradually departed, and in 1905 the newspaper printed its last edition.

Louisa continued to write for several Sydney-based publications, and she also produced an extensive volume of poetry.

I have been unable to find out what mental ailment troubled her in her final days, but dementia appears to be the most likely. She died in the Gladesville Mental Hospital aged 72, in 1920. The fight gets to even the strongest of us in the end.

Unfortunately, The Dawn has so far not been included in the National Library’s ‘Trove’ Digitisation Project, despite it’s great historical significance in gaining Australian women the vote, and despite Louisa’s passion and fervour in promoting women’s rights of all description. Do you feel it’s an important part of Australian history? If you do, why not contribute to the project? It’s being run by the lovely Donna Benjamin and she needs your help to raise the funds to make the digitisation a reality. You might also like to follow @digitisethedawn on Twitter to keep up with progress, and to help spread the word.
Rubbish Paragraph
Oh, and as a postscript: yes, Louisa did have a very famous son, but her story is so much more interesting than that, don’t you agree?

[0] http://www.nla.gov.au/guides/federation/people/lawsonl.html

[1] http://adbonline.anu.edu.au/biogs/A100019b.htm

[2] http://en.wikipedia.org/wiki/Louisa_Lawson

Share


Leave a comment

The Language of Marketing

I was absently staring at a new tube of toothpaste this morning as I washed my hair. You have to look at something, right? This one declared “healthy, whiter teeth for longer”. An image of extremely long (but healthy and white) teeth filled my mind, and was immediately pushed out by the technical writer in me asking “whiter and longer than what, exactly?”

Most marketing slogans give technical writers the screaming heebie-jeebies. Not only do they make spurious and vague claims like ‘more fibre’, ‘less fat’, and ‘20% bigger’ with alarming regularity, but the adjectives! I have no doubt that it is actually possible to sell things with sentences that contain only one adjective. And if they do need more than one, I’m sure a comma wouldn’t kill them. I could rant on the folly of adverbs, too, but that is a whole different article.

Why are marketers such terrible writers?

Because customers expect spin, and spin is easy to write. All you need is a handful of adjectives and a call to action: “The new fruity refreshing Globswoddle Fizz is now available. Experience the heady taste of summer today!”

While yelling at the toothpaste tube in the morning might make us all feel better, it is not likely to turn us into marketers just to help an obviously flailing industry. I finished my marketing degree about three weeks before I decided that the marketing industry was the last place in the world I wanted to work. Eventually, I became a technical writer instead, and discovered that I had inadvertently ended up working in marketing after all. Every word we set to paper is marketing in one way or another. If it is going to be read by a customer, then it needs to sell the product. But the last thing we want to write is spin.

Why are writers such terrible marketers?

Because customers want anything but spin, and while spin is easy to write, spinless marketing is not so easy.

Spin is wanted and welcomed in places where it is expected, like product packaging and on the airwaves. When our customers read technical manuals or help text, they are looking for a solution to a problem. If they were suddenly faced with the empty promises of spin, they would lose faith in the documentation, and possibly the product.

However brutal honesty is not required, either. Product documentation should not tell customers that the product cannot fulfill their expectations. Every question needs to be anticipated and answered. The documentation must give the customer hope that their problem can be resolved, their task completed, and their sanity retained in the process.

Effective documentation never tells the customer that a product is terrible (even if it is), and it never tells a customer that they are stupid (even if they are). It never makes over-inflated claims of software brilliance, and it never assumes greater-than-average user intelligence.

Somewhere nestled in there is product documentation that shows the product in a positive light, without the hard sell. Sound easy? Like most technical writing, it sounds easy until you actually try to do it. Some tips for getting started with spinless writing:

Kick adverbs, take names.
Adverbs are a big red flag for spin. Be ruthless and cut them all out. If your sentence requires a modifier, consider what you are really trying to say. If it forms part of an instruction or description (‘The widget can be fully removed by …’), reword it to remove the adverb (‘Remove the widget by …’).

Never call anything ‘simple’.
If you tell your users that something is ‘simple’, ‘quick’, or ‘easy’, and the customer struggles with it (for whatever reason), you are essentially telling them that they fail at life. Try not to insult your users.

Mind your adjectives.
Adjectives are fine in their place. Use them only where necessary, though, and try not to use more than one at a time. (‘Locate the red button’ is fine, but avoid ‘Locate the large, shiny, red button’ that is next to the ‘tiny, silver, shiny lever’).

Know your stuff.
If you can’t describe your topic in a single short sentence, you don’t understand it well enough, and it becomes too easy to succumb to spin statements. You need to be able to give succinct and accurate descriptions for each and every component part, as well as the product as whole. If you are not able to do this, continue to research your product until you can.

Understand the enemy.
As modern humans, we are largely desensitised to advertising, simply because we are so totally immersed in it. Start noticing it. Analyse what language is used, the sentence structure they’ve employed. Work out how you would re-write it to send the same message, but without the spin.

Edit with a knife.
Never say more than you need to.

—————————————————–

This article was originally published in Words: A Quarterly Bulletin for Technical Writers and Communicators. Volume 3, Issue 1: February 2011, with the following bio:

Lana Brindley has been playing with technology since that summer in the 80’s when she spent the whole time trying not to be eaten by a grue. She has been writing since she could hold a pencil, and is currently writing technical documentation for Red Hat. Lana holds business degrees in marketing and information systems, and with any luck will have a technical communicators degree by the end of the year. She works from her home in Canberra, Australia, and occasionally leaves the house in order to berate university students and conference goers about passive sentence construction.

This post has been cross-posted to fossdocs.

Share


Leave a comment

MODY3 for the newly diagnosed

Receiving a MODY3 diagnosis can be a threatening, frightening time. However, by understanding the disease, and knowing what to do about it, you can live a long and healthy life. This booklet will explain what MODY3 is, and will outline some of the changes you will need to make.

Diabetes mellitus refers to a group of diseases that impact the pancreas and how the body stores and uses both glucose and insulin. Maturity onset diabetes of youth (or MODY) is a rare genetic form of diabetes.

There are three main groups of diseases that fall under the diabetes heading:

  • Type 1 is an immunodeficiency disorder, where the pancreas no longer produces any insulin. People with type 1 diabetes require injections of insulin to stay healthy.
  • Type 2 is a progressive disease, where the pancreas will gradually stop producing insulin in the quantities required. Additionally, people with type 2 diabetes will exhibit insulin resistance, where they  can no longer effectively use the insulin their pancreas produces.
  • All other types. This includes latent autoimmune diabetes of adults (LADA), which is a form of late-onset type 1 diabetes; and maturity onset diabetes of youth (MODY), which is a genetic form of diabetes. These types are sometimes referred to as ‘type 1.5’.

Many people with MODY are never officially diagnosed, as it requires lengthy and expensive genetic testing, and even those results can be inconclusive. You might have been diagnosed as one of the other types of diabetes, and your progression has caused your doctor to suspect you have MODY, or you might have been diagnosed as MODY simply because you show none of the usual signs of type 1 or 2 diabetes. Do not worry too much about having an official diagnosis, though. Enough is known and understood about the management of diabetes—and MODY—to be able to manage your condition very well. Over time, you and your medical team will be able to determine with greater certainty what type of diabetes you have, and how best to treat it.

Despite the name, maturity onset diabetes of youth is not late-onset type 1 diabetes. MODY comes in six known forms, although this number could climb as research continues into the area. MODY is referred to as ‘monogenic’ meaning that it involves only one gene, unlike the more common forms of diabetes that have more complex causes, and involve two or more genes. The types of MODY are differentiated by the gene that is involved. About 2% of all diabetes diagnoses are MODY, and about 70% of all MODY diagnoses are of the type MODY3. MODY3 is caused by mutations of a gene on chromosome 12 called the HNF1? gene.

Generally, people with MODY3 produce a very small amount of insulin or none at all. However, if you have MODY3, you probably do not have very high insulin resistance. This means that that you can use any insulin your body produces or that you inject effectively.


To keep reading, download MODY3 for the newly diagnosed

I wrote this manual as a final assessment item for uni. I have no intention of updating or maintaining the document at this stage, however if there is sufficient interest in it as an information resource, I could possibly be convinced 😉

Share