The State of Free Software Documentation

It’s often hard to find good writing about the state of online documentation. Andy Oram writes for O’Reilly OnLamp, and he has contributed a couple of very interesting articles on the motivations of free documentation writers, and the state of free documentation.

Why Do People Write Free Documentation? Results of a Survey was published on 14 June 2007 and contains some very interesting research results.

Although I found the results very interesting, it was the preamble that I found most worthwhile. The assumptions Andy makes about the current state of free documentation online echoes very closely the motivations for creating FLOSS Manuals. Andy outlines four issues that reflect the general state of online docs today :

  • The same questions get asked over and over
  • Users don’t know where to start
  • Information quality is uneven
  • Optimal solutions are often undiscovered

I agree with these issues, but there are two issues I think he overlooked :

Licensing Interoperability

The current licensing situation for free documentation is pretty bad, the main issue being that there is no standard license that everyone agrees to use for documentation on the web. This would not be such a problem if licenses were compatible, enabling the easy transition of content from one source to the other, and allowing the combining of material released under differing licenses. However, this is not the situation now, as Lawrence Lessig mentioned in 1995:

"Even if all the creative work you want to remix is licensed under a copyleft license, because those licenses are different licenses, you can’t take creative work from one, and remix it in another. Wikipedia, for example, is licensed under the FDL. It requires derivatives be licensed under the FDL only. And the same is true of the Creative Commons Attribution-ShareAlike license that governs Opsound content, as well as much of the creativity within Flickr. All of these licenses were written without regard to the fundamental value of every significant advance in the digital age — interoperability"

With free software, the GPL is the standard license, and since no such agreed ‘standard’ exists for documentation, then improving a document using multiple sources cannot occur.

FLOSS Manuals has decided to use the GPL. Since there is no ‘standard’ for docs (I have written about this in an earlier FLOSS Manuals post about the problems with the GNU Free Documentation License), then we might as well side with the programmers until this interoperability issue is resolved. Documentation is after all, often included with software, and it’s easier for programmers if they don’t have to worry about license compatibility problems between the documentation and the source code. However, one tactic we still might employ is to dual-license in Creative Commons so that bloggers etc could more easily copy and adapt documentation for their own use.

“It’s not a bug. It’s an undocumented feature.”

Andy Oram omitted the ever frustrating fact that often the documentation just doesn’t exist. This is always going to be the case as the first step of a software development project is seldom to write the user manual. Documentation is usually last on the to-do list, and sometimes it falls off the checklist all together. This might be understandable if the project was new. However, there are many times I have looked for documentation and found it doesn’t exist anywhere, even for relatively mature software. The only remedy for this is to hope that more software developers take documentation more seriously and develop a documentation team alongside their coding team. The other option is that community-led projects like FLOSS Manuals fill the gap. This is what we are trying to achieve but our efforts are only needed because the state of documentation online is so bad. In a better world, there would be no need for such an effort.

I enjoyed Andy Oram’s article very much and the results of the survey are well worth reading. You may want to map the findings against “What motivates Wikipedians: motivations for Wikipedia content contribution” (PDF) by Oded Nov. You can find more of Andy Oram’s writing here (thoroughly recommended):

06 February 2007

I-TASC expedition 2006/2007

Seas are relatively calm. We have a few more birds appearing out the back of the boat, but otherwise, all is the same.

Advice from the bottom of a well, Part 4 : extras
I thought I should write down some last bits I had forgotten in the last sections about what to bring if you ever find yourself going to SANAE.

* gloves
I have thought about the glove issue a bit. In the last week or so at the base, I found that the large windproof mitten gloves (the gloves without fingers) are excellent for warming up your hands while outside. If you get cold hands then you can take off any glove inners and put your ‘naked’ hands into the gloves. The natural warmth of your hands will warm your hands and fingers faster than any other way (except a heater). So bring a good pair of robust windproof mittens. Also, I mentioned earlier, merino glove inners, and lastly consider getting a really good pair of warm working gloves.

* Butane Solder Iron
If you are going to work with any electronics, then bring a butane soldering iron for working outside. It would pay to buy this in Cape Town as most airlines won’t allow them onboard aircraft in checked or onboard luggage.

* cups
It might seem a little trivial, but there is a lack of good cups and glasses at SANAE and it’s the little things that make a difference. Bring a big thermos flask type cup. Good for coffee up on the monkey deck on the boat, and good for long cold drinks at the base when you come in from a hot day’s work or a sauna.

* tradeables
Bring some extra CDs and DVDs, if you don’t use them, they are good currency on the boat for trading with the crew, and if you have a laptop with a dvd burner, you will also make good alliances if you don’t mind a bit of extra work ripping/burning.

* video
If you are going to take video you most definitely need a good ‘Zepplin’ microphone sock. You won’t get any outdoor sound without it.

* currency
Make sure you bring enough currency with you to pay for the communications and shop bill you might accumulate on the boat.

* USB stick
These days it almost goes without saying, but I’ll say it anyway. Bring a USB memory stick, at least 1GB. You need it if you want to send emails from the boat as you need to write emails, transfer them in a text file to a stick, and then give it to the radio comms officer. The officer then copies the text into an email and sends it (all emails leave via the same Agulhas email account). You get replies the same way except the radio officer prints them out for you. However, even without this, I used my USB stick several times a day while at the base.

* Wireless Router
Don’t leave home without one.

* Arduino
I wish I had a small PIC set up. If you know what an Arduino is then get one. We had to build a circuit on the fly on this trip for a reasonably critical role, but if we had an Arduino unit we could have done the same thing faster and more reliably.

* Radio
For listening to Radio SANAE!!!

* Disk Space
Make sure you have lots of disk space available for photos etc – consider an external disk.

* Rechargeable Batteries
Bring plenty of rechargeable batteries.

* Sunscreen
The stuff SANAE provides isn’t that good. Bring your own and make it as strong as possible.

* Extension cords
You won’t find any extra on the boat or at SANAE so bring your own extension cords and power boxes, especially if you are using plugs that are not South African plugs…bring as many extension boxes and cables as you can, you will use them all.

* Walkie Talkies
Not absolutely necessary to purchase for an individual, but useful for the team.  They can be expensive, but 2-way hand held radios are rare at the base. I would find out what kind they use (what frequencies they work on) and then buy a couple. This is the expensive way but it has the advantage that you can always have a radio that is on the same channels as the SANAE radios. A cheaper way would be to buy 2 or 4 small walkie talkies of the cheap variety for comms just within the crew.

* Attitude
Bring a good one 😉 – on this note -> you can expect tensions amongst your crew. It’s _normal_. Part of the experience of the trip is learning how to deal with team dynamics. I recommend you expect that tensions will arise and you prepare to forgive, forget, and move on as fast as possible. On-going issues need to be addressed but there is a lot to be said for a generosity of spirit. Provide your teammates with comradeship, and good feedback, never criticise the person but instead address the issue at hand with an attitude of improving the situation and not apportioning blame. Be prepared to own up to and laugh at your own mistakes. Find out what motivates your teammates, and work on that. They are old rules, you can take them or leave them, but trust me on the sunscreen 😉


05 February 2007

I-TASC expedition 2006/2007

Last night we moved through the last of the ice. it was sad to see the last remnants disappear behind the ship. While we were going, cutting through large islands of soft melting ice, the sun gave us a beautiful farewell sunset. It was so vibrant as to look almost fake.

Today I will sleep a little en leer Nederlands. It’s getting a bit of a swell in the sea… I had forgotten how foggy that makes the mind.

03 February 2007

I-TASC expedition 2006/2007

Back on the ship. It was an amazing helicopter ride from SANAE IV to the ship. I was very sad to leave the continent and couldn’t help shedding a tear or two on the trip back to the Agulhas. We left the base, swooped over the AWS, and then turned and dropped spectacularly over the Nunatuk…those chopper guys, they like to impress and I’m glad for it.


It was also amazing to fly over the ice shelf and see the ice stretching away to the horizon with ragged cliffs. Then the Agulhas. Beautiful on the sparkling blue water, cruising slowly in anticipation of our homecoming. She’s a queen of second homes amongst an array of second homes we have experienced on this trip. A good friend spent much of his life on the sea in the NZ Navy, and as a pilot in Dunedin. I could never understand how he could love it so, as it seemed a very harsh existence, but seeing the Agulhas again filled me with warmth and respect for the ship and the strange existence it offers. It made me realise how lucky I have been to have had a glimpse of life at sea, and I can see its attraction.


I was also sad to leave Zama behind. We had a tight cabin, the boys of B10. 3 of us came back but Zama was asked, just two weeks ago, to stay. I wouldn’t like to have been in his situation – the other over-winter crew had 2 months to train and many more to prepare psychologically for spending 14 months on the continent by themselves. However, Zama had no such luck. He decided to stay, and I am sure he will have an amazing experience. It would have been hard for him not to have said his goodbyes properly to family and friends.


It was also great to finally be able to call Lotte and talk for a whole 10 minutes! ah… the small pleasures of modern naval communications.

Anyway, we wait here on the ship for 2 more days, and then we move out across the Southern Ocean. I hope the seas are good. We were fortunate to have extremely good seas on the way here. I hope we get that luck twice. Leon (one of last year’s winter team) is hoping to see at least 10-metre waves and hopes the ship will surf some… I don’t share his enthusiasm… maybe the trip home will cure me of my new found respect for life at sea 😉

Outside, the crew are loading containers on the ship. There are a few more loads to come from the base, I think they expect to be finished with this tomorrow. They bring the containers down a steep bank cut they made in the ice. At this time the Agulhas is parked with its nose on the ice shelf and the containers are swung aboard.


So, I’m spending the days till we leave watching stupid American tv series, and taking photos. I am practising birdy shots with the telephoto…its kind of like skeet shooting… you follow the bird, trying to pull focus manually as quickly as you can, panning the cam at the same speed, and then pressing the trigger to get the perfecin-flightht shot… It’s great fun and quite addictive – I’m sure if they invented cameras before guns there would have been a lot less game shooting in the world (and consequently more animals still around, and the world would be better documented!). I got a couple of good shots, but I am anticpating that perfect trophy to hang on the wall, maybe an albatross in flight, or two snow petrels in frame with perfect focus.


First Born is sleeping through the day. He worked hard these last days outside.

When I get back to Cape Town I fly from Jo’burg on the 18th of Feb. Spending my birthday mid air 🙂 Then I land in Sydney and I hope I get to see Mr Snow, Zina, and the good Doctor Gillian for a day or so before winging it to NZ. Not long to go now before familiar shores and faces populate my existence… now i just got to strategise the best moment to shave…


02 February 2007

I-TASC expedition 2006/2007

The unit is installed. All is running, and we are also. Helicopter flight out in 1 hour, the base is like a ghost town. I’m now busy copying Boston Legal series 2+3 for the long wave home…

We will update from the boat, might take a day or so

Need some coffee….

Check these :
Groundhog Weather : [24hrs][Archive]

Congrats to all involved 🙂

01 February 2007

I-TASC expedition 2006/2007

News news news…we have had our travel plans altered and we leave tomorrow (the 2nd) in stead of the 3rd. This means we have one less day to get it together…


For those interested, here is the circuit we built yesterday (whoever has to do the maintenance on it next year, there is a copy of the full diagram provided.)


31 January 2007

I-TASC expedition 2006/2007

It’s been a busy few days. We fly out to the boat in two days and so it’s a mad rush to get everything done. Tom, Amanda, and First Born have been very busy outside with the AWS unit, setting it up with the wind turbines and solar panels. It looks fantastic and they have done an excellent job.

It’s been pretty cold these last days, and they have been outside most the time, coming back looking frozen. Today the wind turbine was finally working, and tomorrow we install all the AWS and communications equipment.

In the meantime, I have been inside working on the networking systems (writing scripts etc). It’s been warmer work than that of my colleagues but possibly a little bit more boring! 😉

Still, today was rewarding. I was looking for a way to restart the computer that will be in the AWS. If the batteries fail in the unit (if there is a storm during winter or other reason), then we need a way to power the computer on once the batteries have recharged. There are a number of ways this could be possible with some machines (bios settings for example) but this computer supports none of them. The computer has an on/off button which, if depressed momentarily, starts up the computer. So, we needed a circuit to solve this. After wedging off a plastic panel, it appears that shorting out the button momentarily would also start the computer.

So, we needed a circuit that would do this automagically. I wondered if a relay would do this. A relay will close a circuit when power is applied, but it couldn’t do this on its own, so I emailed some friends. We had excellent brainstorming sessions, and Mr Snow and Matthew Biederman helped shape the idea of what was necessary. But we had no circuit. So I visited Pierre (one of the scientists here) and naively asked him if a series of relays might do the trick. Before I knew it, Pierre had sketched out a circuit on some paper and helped me source the parts. I built it, but it didn’t work… so, Pierre then troubleshot the circuit, which took a good 6 hours or so. I could mumble some agreements, and nod a few times, while Pierre whizzed through the possible causes for many problems we were having with the circuit. Finally, we had a circuit that works. It might look a little crazy, but it does the job.

So now, if the batteries fall below 6 volts, the computer is more than likely to be turned off. Then when the power rises, at 10 volts the circuit triggers some relays, one of which short circuits the on-button for half a second or so and the laptop starts. Pierre is now drawing the circuit diagram and tomorrow we will publish it if anyone wants to use such a thing.

Anyways, off to bed now, a big day tomorrow.

29 January 2007

I-TASC expedition 2006/2007

Today was a big day for Tom and First Born. They have been working really hard on the AWS unit, preparing it for installation, and today it actually goes out to the field. I think they had to wait quite a long time before the crane crew could get through the other tasks they had for the day, but just before dinner, the AWS was swung out on the crane and placed on the back of a Skidoo. After dinner, I think they will try and place it upright, although it’s getting pretty windy out there right now. In the meantime, I’m inside testing the scripts for delivering the data from the unit to the WWW.

We brought down some projects to enact on behalf of artists. We didn’t have much time to prepare for the trip, so I managed only to get four projects, plus we are assisting the Media Shed in Southend by the Sea (UK) to do some workshops using weather data.

Today I pulled Tijmen Schep’s ‘Coke Bot’ out of the suitcase and soldered up its solar panel. It’s a cool installation that is a coke can (pretty much the last thing you want to see in Antarctica) with a noise robot inside that beeps and is powered by a small solar panel. I really like it; it’s a cool installation for here as it plays with the ironies of reusable energy and recycled materials. Tomorrow I will put it out on the ice and document it, and then leave it inside the base for the next I-TASC crew.

There are some other projects by artists but I’ll unveil them as we install/utilise them. Look for documentation of Tijmen’s can tomorrow.

Advice from the bottom of a well, Part III : basic tools, and cameras
All right… this will be a short session on what to bring for a SANAE residency. They have pretty much everything here, so you don’t need to bring much (unless you need specialised tools). In fact they have a very well-equipped workshop for electronics, a carpentry room and a metal shop, so you can do quite a bit here if you have to… so there is not much you need.  I mention just a few things that can be handy… personally I think you should not even cross the road without a good Leatherman or Victorinox. I have one of the later, and it proves useful almost everyday and unequal in the field when you need to do almost anything.

Additionally, I think you need to at least bring a soldering kit and all the wires and cables you can expect to use. Don’t bring pre-made cables, they are always too expensive and too chunky to freight in any quantity. Buy as many different types of connectors as you can.

Bring a roll of gaffer tape… it’s always useful….

That’s about all I have found that is useful… for everything else I used what they have here….

Some small advice with cameras… get a good digital camera. I don’t mean a pocket-size cam, I mean a good SLR camera with interchangeable lenses. Don’t settle for anything less than 6 megapixels. You won’t regret it. I purchased a second-hand Canon 300D with a 18-55mm lens. In addition, I brought a screw-on wide angle adapter which had produced some good shots but I think the wide angle is optional. What you shouldn’t do without, is a telephoto… its absolutely essential. You will see many things from the boat that you can’t get close to (penguins, birds, whales, icebergs) that will look beautiful in a telephoto but like a dot in a 18-55mm lens or similar.

Whatever camera you get, don’t leave without _two_ rechargeable batteries. There are periods when you are away from the base for a day or so and you will need that extra battery. Also, don’t even think about coming without a polarising filter. It will help cut through the glare of the water and bring out the beautiful blues of the ice and the sky… it’s really essential. Lastly, get a small camera bag that has good padding, that you can sling over your shoulder and run out the door at a moment’s notice. Nothing too heavy, just big enough for your camera and your lenses.

Of course, make sure you have lens cleaner stuff etc (all the normal camera things).

If someone in your team has a small digital camera, this will still be very useful for having in your pocket if you need a quick shot but you are somewhere awkward (on the end of a rope in a crevasse for example).