On Writing, Tech, and Other Loquacities

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


Leave a comment

Open Source Developer’s Conference 2011 – Call for Papers!

The Open Source Developer’s Conference (OSDC to its friends) is being held in Canberra in November this year, which is a little bit exciting, and they have just opened their call for papers.

Also this year, for the first time, they’re asking for miniconf proposals too. I would love to do a whole miniconf on open source documentation, but I’m not sure I have that kind of stamina. Of course, If you’re interested in helping me out, let me know!

I spoke at OSDC last year, when it was in Melbourne, and the footage is on my videos page. I thoroughly enjoyed the experience, so it will be interesting to see what kind of event Canberra can put on this year.

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

Taking a Walk on the Open Side

Tonight, I gave a talk about Open Source for the Canberra Society of Editors (who invite the ACT branch of the Society of Technical Communicators, of which I am a member). There was a reasonable crowd, who all seemed interested and who asked lots of questions. It is always satisfying to give a talk and to see a light go on in people’s eyes, see that spark of something flash in their faces as they learn something new, think about something in a different way, or experience a different perspective. That, my friends, is what makes it all worth it.

This talk wasn’t recorded, unfortunately, so I won’t be providing video, but I can tempt you with my slide deck. Unfortunately, my slide decks don’t tend to have many words on them, so you might not learn much, but there are lots of pretty pictures. And if you were present at the discussion tonight, thanks for coming, and I hope you found some inspiration. Please feel free to drop a note in the comments if you’re after more information about anything.

If you do want to know more, there is a fairly severely shortened version of it in this month’s edition of Words. I’ll put the full text of that up here in the next few days, or you could head over to their website and check it out there.

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


3 Comments

There’s nothing wrong with Ohio

(Except the snow and the rain)

It looks as though I’ll be winging my way back to the United States again shortly. I’ve been asked to speak at the Open Help Conference in Cincinnati (and one day soon I’ll learn how to spell it!), Ohio on 3-5 June.

If you’re half as dedicated as I am to American candy, get your orders in now. There will only be so much room in the suitcase …

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

FOSS Training

I was privileged enough to be able to attend linux.conf.au in Wellington in January. While there, I caught Bob Edwards’ and Andrew Tridgell’s talk on “Teaching FOSS at Universities” (video of which can be found here). It intrigued me.

Open source software development is very different to developing software in a more traditional, closed source environment. The aim of the course is to teach students how to go about working within the open source community. It covers the practical aspects of checking out code from a repository, submitting patches, and undergoing code approvals and reviews. It also looks at some of the less tangible aspects, like what’s accepted and expected within the community, the motivation behind project development, and governance. The course also goes into some detail about documentation.

Documentation for open source projects is not quite the known quantity that it can be in many proprietary software environments. I once had a developer I was working with describe it as “we live in the Wild West out here”, and – at least to an extent – he makes a good point. While writing for an open source project may not be as wild and exciting as that sentence makes it sound, it can sometimes be unpredictable and, at times, incredibly frustrating. Frequently, a book has been written and reviewed in preparation for a release, only to find at the last minute that a feature has been pulled from the version, a component has suddenly been renamed, or the graphical interface has had some kind of redesign. All of these things happen to open source writers on a regular basis, and frequently the only solution is to pull an all-nighter, get the changes in, and have the document released on schedule. And that’s only if you were lucky enough to find out about the change with enough time to spare before release!

So how does a writer plan for and write a documentation suite when there’s so much unknown in a project? The answer is – perhaps ironically – to plan ahead. You can’t plan for every contingency, nor should you. But if you have a plan of any description, you’re going to be better off when things start to go wrong. Pin down the details as best you can as far ahead as possible. But don’t leave it there, continue to review and adapt your plan. Keep your ear to the ground, and constantly tweak your schedule and your book to suit. If something comes up in a mailing list about a feature you’ve never heard of, don’t be afraid to ask the question – “Does this need to be documented? Will it be in the next version? Where can I get more source information?”. Another trick is to make sure you build in ‘wiggle room’ to your schedule, in case you suddenly discover a new chapter that needs adding, or a whole section that needs to be changed. If you’re consistently a few days or a week ahead of schedule, then even a substantial change should not throw you too far off balance.

Just like a ballet dancer, technical writers need to be disciplined, structured, and organised. But you also need to have grace, poise, tact, and – most importantly – flexibility.

Thanks to Bob and Tridge, I’ll be lecturing the 2010 FOSS course students at the Australian National University later this week. I’ll also be contributing the textbook that is being developed for the course. True to form, it is being built by and for the open source community, using open source tools (including Publican which has been developed in-house by some of my esteemed colleagues). Watch this space for more information.

Cross-posted to FOSS Docs
Share