Blog Archives

More on open source and technical writing

A few weeks ago I wrote a post about how technical writers can help open source contributors get started, and in so doing ramp up our own contributions to open source projects. A colleague has now pointed me to another great post on a related theme: Documentation as a gateway to open source, by James Turnbull.

My post focuses on the complexity of the open source world, which makes it difficult for anyone to get started, even to make a small fix to the source code or the docs. As technical writers, we can help people jump at least the initial hurdles. We can add docs that describe how to complete any relevant licence agreement, edit a code file or a doc page,  send an update for review, and eventually submit the update to the repository. In documenting the process, we become our own test subjects, as we need to go through that very process in order to document it. Sound familiar? It’s what we do best.

James Turnbull’s post takes things further. He describes how to:

  • Find a project that you can contribute to.
  • Consider the etiquette of the open source community that you’ve chosen, before jumping in and making a contribution.
  • Decide what type of edits to make. Both James and I describe READMEs as a good place to start. James goes on to examine strings, errors, and commands, and a few other file types too.

If you’re interested in open source, I recommend James’s post. It’s a good read.

Doc sprint at Write the Docs day Australia

Yesterday was the very first full-day event held by Write the Docs Australia. In the morning we hosted a writing sprint, featuring five open source projects. The afternoon was devoted to five presentations. Of course, coffee and conversation happened throughout the day.

Although short, the writing sprint was fun and productive. Participants learned about open source, fixed doc bugs, discussed information architecture, and got to know some style guides.

At the start of the day, we invited people to pitch for their projects. Then each of the pitchers chose a table in the room. The other attendees decided which sprint to take part in, and joined the relevant table. These were the five sprints:

  • Dart, led by Sarah Maddox
  • Kubernetes, led by Jared Bhatti
  • Cyrus (email), led by Nicola Nye
  • webpack (JavaScript module bundler), led by Chris
  •, led by Geoff

What happened in the sprints

I ran the sprint on the Dart docs. Dart is a programming language with accompanying libraries. Developers use Dart to create apps that run in a web browser (Dart code compiles to JavaScript), servers and command-line applications, and mobile apps via the Flutter SDK.

We had four contributors taking part in the Dart sprint. Our focus was to update selected pages to match the Google style guide. We produced the following pull requests:

The Kubernetes sprint closed a number of issues, pretty much all those that had been allocated to the sprint!

At one of the tables, people spent much of their time discussing information architecture and doc design, using the open source project as the basis for the discussion. The project leader collected two pages of useful feedback as a result.

Things people learned

For many participants, the sprints were their first venture into the world of open source. A participant asked me, “So, after today, can I continue contributing to the docs? How would I do it?” She was pleased to hear that she could continue participating, and she’d do it in the same way as during the sprint. Our table also discussed contributing to open source projects in general: read the contributors’ guide for each project, be aware that pull requests do require work from the repository owners.

Participants needed a basic knowledge of Markdown. I gave a quick overview of the syntax, to get them started.

For the Dart sprint in particular, it was useful to learn a bit about the language. The sprinters’ guide included a quick introduction, and we ran a sample in Dartpad, to watch the code in action.

The open source projects we focused on are hosted on GitHub. Participants learned the GitHub workflow: how to edit files in a GitHub repo, submit a pull request (PR), receive feedback on the PR, make changes to the files in the PR, and re-submit the PR.

For the Dart sprint, our task was to update pages to follow the Google Developer Documentation Style Guide. One contributor was delighted to note that the style guide agrees with her tech writer intuition, overall. Another contributor reviewed a very long page, checking the style guide when in doubt. She found that, in most cases, the page did follow the style guidelines. I suggested that she add this information in the comment when she sent her pull request, as it would be useful information for the repo owners.

It was hard work

It’s hard work editing pages to follow a style guide. The Dart table stood out as being the quiet, focused area of the room. We were all deeply in the zone.

There came a touch of humour to dilute the hard work: a comment from one of the sprinters to Swapnil Ogale, Write the Docs organiser, after he’d been chatting with our table for a while.

Swapnil: “Good, OK, I’ll leave you to it.”

Sprinter, with a smile: “Yes, leave me alone. I’ve got a lot of work to do.” 🙂

Difficulties people encountered

People had trouble with the GitHub workflow at the start of the sprint. For example, when a sprinter first tried to enter a comment on an issue, an email verification request popped up. The experience was confusing.

Some people found it difficult to concentrate in the noisy environment of a sprint, and they felt stressed that they wouldn’t have time to achieve anything in the short time frame of the half-day sprint.

Three hours is a very short time for a doc sprint, particularly when the sprinters are new to the environment and the docs.

Feedback and thanks

If you were at the Write the Docs day, I’d love your comments and feedback on the writing sprints. I’m sure readers of this blog would be interested to know what you learned from the sprints. The owners of the open source repositories would like to know how they can make it easier for people to contribute to the doc sets.

A big thank you to everyone who took part in the writing day and contributed to the docs!

One laptop per child OLPC Sydney

On Friday night I attended a SLUG meeting where Pia Waugh and Jeff Waugh demonstrated the XO computers used in the One Laptop Per Child (OLPC) project. The little machines are a cute, impressive package. The OLPC project is visionary, intriguing, and I think bound to grow beyond what’s yet dreamt of in our philosophy.

The OLPC project aims to give a specially-designed computer laptop, the XO, to children in remote and underprivileged areas of the world. The goal is to give these children access to the most up-to-date technologies for learning, experimentation, self-expression and collaboration. The project was first announced publicly in 2005.

This blog post is about the things that struck me most during the presentation in Sydney on Friday 28 March 2008. There’s a lot more information on the OLPC web site about the XO machines and about the aims, history and growth of the project.

The XO hardware

Pia and Jeff brought along a few of the XO laptops. Before the talk started, I wandered to the front and picked one up. First, I had to figure out how to open it. I dare say a five-year-old child would have figured it out in two seconds. It took me a bit longer, but eventually I flipped up the two bunny ears and opened the lid.

The machine is small — you can comfortably hold it with one hand and press the keys with the other. It has a handy grab bar at the back, so there’s little chance of dropping it while you tap the keys. The outer casing is quite tough, and the keys are overlaid with a soft rubbery cover. Jeff mentioned a use case that has been tested:

You can spill a glass of wine on the keys and they’ll still work.

Though, he said, that’s not necessarily a use case that was designed for 😉 since the principle users of the XOs are children — what’s more they’re children in remote and disadvantaged areas of the world.

You can also throw the XO against a wall, and most of it will still work. It is recommended that you close it first. (Wink again 😉 )

Jeff is a mine of interesting titbits. Here are just a few of them:

  • To conserve power, the machine goes into low power mode three seconds after you stop hitting the keys. But the screen stays alive much longer.
  • There is no hard drive, just flash memory. This makes the machine very robust.
    • That’s the throw-it-at-a-wall use case.
  • You can put the display into black-and-white mode — triple the resolution. This is great for use as an eBook. You can twist the screen round, to make the machine even more compact while reading.
    • This is great for reading under a tree.
  • Two round holes conceal the (video) camera and microphone. Above these are two pinprick lights, showing when the camera or mic is activated. These lights are wired-in hardware, not software-controlled.
    • So there’s no way to trick the child into being recorded unknowingly.
  • The battery lasts six to eight hours and can handle 40 degrees ambient temperature. There are a number of ways to recharge it, including situations where there’s no electricity:
    • Hand-held crank, in the same cool dark-lime green and robust chunky design as the laptop.
    • Solar power recharger, which can be located at a school so that the children can recharge while in class.
    • Cow power — attach your cow to a long pole and walk it round in circles, charging the battery.
    • The normal electric recharger we all know and love.
    • Foot crank.
    • And so on — new and funky rechargers keep appearing.

The XO software

Endearing and clever — those are the terms I’d pick.

What’s endearing is the appearance of the machine itself and of the user interface. The XO motif is used cleverly, to represent little people —‘O’ over ‘X’ representing a head and body. Click the ‘Neighbourhood’ key on the keyboard or the corresponding icon on the screen (both will get you to the same place) . Now you see little XO icons dotted around the screen, representing others on your mesh network.

Pia showed us around the user interface, activities and collaborative features. It’s a little like Facebook or other social networking tools. You can choose your friends and interact with them. Other nearby networks will appear too, even if you don’t have access to them.

The applications are called ‘Activities’. Examples might be a web browser (Firefox); Chat; a text processor (Write); and so on. When using an application, you can choose to share it. Then it will appear on other people’s Neighbourhood screens and they can jump right in and collaborate with you.

The designers of the user interface have avoided text as much as possible. They are also attempting to steer clear of a file system display (like Windows Explorer). Instead, there’s a pie chart to show which activities are loaded, and a ‘life stream’ of all the things you are doing.

The focus is on learning, of course. But not only on learning pre-determined material. The focus is also on creative activities — composing music, writing code, experimentation, and collaborating with others in your network.

The mesh network concept is pretty cool. James Cameron, an Ozzie outback software engineer, hung one XO in a tree and took another for a ride in his ute. He got them pinging each other at a distance of two kilometres. In Peru, they’ve managed to bring internet access to a remote town by putting an XO every two kilometres over a distance of thirty kilometres.

Stephen, a young boy who is an XO wizard, showed us some Python code he’d put together. There are three software development environments:

  • Pippy — based on Python, allows you to code, run and share with ease.
  • EToys — based on SmallTalk.
  • TurtleArt — a cool graphical tool, where you drag and drop components into a flowchart.

OLPC Australia and region
Pia and Jeff mentioned lots of trials happening in New Zealand, the Solomon Islands and regional Australia. The objectives are to give the remote and disadvanted communities access to cool educational stuff.

The future

The open source community is developing new applications for the XO all the time. Here’s one that caught my attention:

Soon, a cog on the keyboard will give you access to the source for the Python front end. So the children will be able to ‘mess up’ their own PCs by changing the code.

They can reinstall from a friend’s PC via the mesh network, or just switch from customised mode back to the default.

My conclusions

A big thank you to the Sydney Linux Users Group and to Pia and Jeff. And thank you to Atlassian for hosting the event in their Sydney office.

In the past few months, I’ve seen pictures of the laptops and I’ve followed Anne Gentle‘s excellent and in-depth blog posts on her work with the OLPC project. Now it was great to play with the machines myself, and to meet Jeff and Pia who are so absorbed in and committed to the project.

My husband Peter was at the meeting too. Afterwards, he said that he’d like to know more about the politics behind the project. Now, that’s a really good point. What sort of political impediments do the OLPC guys have to work around, to get the laptops out to the areas where they’re most needed? Is every country actually eager to allow them in? A couple of people mentioned that we might be seen as foisting Western technology on the children of the world. But does any country or political force actually see it that way?

I’ll be following this project with great interest, and also looking into how I might become involved. Ann Gentle has jumped in already. I wonder if the Australian branch needs the input from a technical writer like me?

%d bloggers like this: