I want to ride my bicycle: A personal history

When I was in high school, probably about 15 years old or so, I found out that my best friend’s parents let her cycle the several miles to the town library. Not one to pass up on an adventure, I begged my own parents to let me join her on a trip. They gave in, but only because my best friend had been doing it for over a year already and they knew I wouldn’t be alone.

The journey on a map looks quite straightforward – down one big long road and then up the other again.

Down the hill on Rt 32 in Montville, Connecticut
Down the hill on Rt 32 in Montville, Connecticut
The route on the map of how I travelled from home to the library
The pillgrimage from home to the Raymond Hill Library

Of course, it was down a great big hill and then up another great big hill. So, she and I would meet at the bottom of a great big hill and we’d cycle up the other hill together. It was only four miles, but it was a fantastically far distance to go without my parents around – at that point, the farthest I’d strayed from them without being driven was a quarter-of-a-mile walk to deliver something to the post office.

It was then that I realised the freedom that the bicycle could offer me. If I could cycle somewhere, I didn’t need to wait for my parents to give me a lift. I could cycle to the library, to my friend’s house, or to the grocery store two miles away. I didn’t do it for fitness, but to get out of the house.

By 17 years old, I was quite happy to cycle the 8.5 miles to a friend’s house across town, bicycle laden with lunch, a change of clothes, books, and whatever else I’d want with me for the day’s adventure. I still remember cycling across town one sunny summer day – at 90F (32C) and humid. I wasn’t bothered, just stopped to take a drink of water every mile or so.

[At this point, I’d include a photo of me with my bike, but I can’t seem to find it just now!]

I wore a helmet (legally required until age 18), but not fluorescent colours. It’s not that it was safer to cycle in my hometown back then, but just that it hadn’t occurred to me that it could be very dangerous. The main roads were wide so I could cycle in the gutter and leave plenty of passing space and there weren’t many cars on the back roads. Actually, the only thing I was ever really scared of on my bike was an angry dog tied out in a garden at one of the houses halfway up the steepest hill – he pulled the chain off the doghouse one day and chased me the rest of the way up the hill, starling at my heels.

I got a car at age 18, gifted from an elderly aunt who could no longer drive. I’d graduated high school, started college part-time and worked part-time. Driving saved time, especially with the distances involved (10-20 miles, depending on which campus I had to drive to), so I all but abandoned my bike to the shed.

I secretly celebrated the handful of times when my car would break down on days that I didn’t have class and I was able to cycle the five miles to the shop where I worked. I remember my family getting upset that I was using my bike to commute rather than asking to borrow a car. In the years since I had started my cycling, traffic had gotten busier along the main thoroughfare and they were worried about my safety. If anything, I worried less as my familiarity and comfort with the roads increased. I prided myself on being one of only a few cyclists in the entire town (I knew the other two, as our paths would very occasionally cross).

When I moved to Edinburgh, at age 21, I initially didn’t take a bike with me. I spent the majority of my first year of my undergrad wishing I had a bike, though, to visit the farther corners of the city in the free moments between studying and societies. When I returned for my second year, I brought with me a budget mountain bike from Wal*Mart that would suffice for the few years I had left of university and wouldn’t make me cry if it rusted to bits.

The first time I tried to cycle on the streets of Edinburgh, though, I discovered the fear. The traffic was on the wrong side of the roads, the signal lights weren’t overhead where I was expecting them, the roads that I frequently walked were one-way in the opposite direction, and there were cars and buses and taxis! I found myself paralysed. I remember standing outside my flat with my bike, unable to get on it and cycle on the roads. I walked to the Meadows and cycled along North Meadow Walk. I intended to cycle back along Melville Drive but couldn’t bring myself to join the road. I cycled back along the pavement until I reached the North Meadows Walk cycle path again. Confused by my nervousness I looped around the Meadows a few times, avoiding pedestrians as best I could, until I finally made myself cross at the pedestrian crossing at the East end of the Meadows, turn Right onto Melville Drive, and cycle on the road back to the West end of North Meadows Walk. I mounted the pavement and congratulated myself but didn’t do it again for awhile.

I remember taking it slowly, re-learning how to cycle in Edinburgh. I remember mostly cycling with my flatmate who was, himself, an avid transportation cyclist. He cycled to class most days while I walked, but if we had somewhere to be together and needed to be there fast, then we could cycle and I would cautiously follow him. I remember the day I raced him across quiet streets to get to flat viewings and we were both surprised by how I’d taken to cycling. It took two years for me to cycle Edinburgh with confidence.

After I graduated, I donated my rusted bike to the Bike Station. I moved down to England where my boyfriend was working and found myself again wishing for a bike. There was a particular style of bike that I’d seen locked to fences in Edinburgh but couldn’t seem to find new or used! I was desperate for a racing bike like I’d used back in Connecticut, but with a dropped top-tube so I could still occasionally wear skirts. I managed to find one on eBay, collection-only in a village outside Nottingham. I fell in love with the cherry-red beauty and duly collected it and had to cycle it the 5 miles back into Nottingham because I couldn’t take it on the bus.

Red bicycle in the bike storage space
Cherry red 1984 Raleigh Stratos, affectionately named “Caroline”

Then, I moved to Cambridge. Cambridge, I’m told, is a cyclists dream in the UK. I found it more terrifying than cycling in Edinburgh because there were more cyclists and the drivers were more impatient with us. Where drivers would pass me wide in Edinburgh, or wait behind me until they could, in Cambridge they’d come within a hair’s breadth. In Cambridge, I had punishment passes, SMIDSYs, and a healthy dose of “damned cyclists”. Cambridge was better in some ways, but much worse in others. But I had a bike that I loved and a need to get out and see the city. I cycled into town every Saturday and Sunday from where I was staying in the outskirts, despite bad weather and impatient drivers. I loved it, despite everything.

I moved to Norwich where my fiancé had gotten transferred and took the train into Cambridge daily. That was when I invested in a Brompton which forced me to leave my beautiful and beloved Raleigh in the storage cupboard in Norwich rather than risk theft or mud at the bike shed at Cambridge station. I was sad about not riding my road bike, but the Brompton was much more practical. After a year and a half of English cycling, I moved back to Scotland and resumed my cycling in Falkirk and Edinburgh.

Raleigh Stratos and Brompton bicycles, propped up against the shed
My Raleigh Stratos and my Brompton

Things in Edinburgh had changed, noticeably, in the time that I was gone. The cyclists I saw weren’t only other students. There were more cyclists, more high-vis, more helmets. There was strength in numbers reminiscent of I’d seen in some parts of Cambridge but the drivers still didn’t have the impatience of the drivers in Cambridge. I couldn’t cycle as hard or as far as I’d gotten accustomed to on the flat roads of the English city, but it was fine. There was more of a community of cyclists in Edinburgh, rather than the isolation of cycling in Connecticut, or the free-for-all folks-on-bikes in Cambridge. There were a few sporty cyclists, some students, and a whole load of folks who’re just enjoying getting to work.

Before returning to Edinburgh, I didn’t see myself as a cyclist. I was just a person who happened to ride a bike. It was only in a conversation on the phone with my dad, when I’d commented about how much cycling had changed in Edinburgh and how happy I was to be cycling there again that he told me “Oh, Denise, you’ve always been a cyclist, you’ve always loved your bike.” That’s when I started reading blogs by cyclists, learning about cycling campaigns like Pedal on Parliament. I wrote a blog post about it, at the time, describing the different categories of cyclist that I could associate myself with.

I still don’t really see myself as a cyclist, it’s not my profession and it’s not even what I would consider a hobby. I only really ever cycle as A-to-B transport, but cycling is my favourite mode of transport and advocating for the bicycle has become my passion. It’s been really hard giving it up while I was pregnant, and now because I can’t carry an infant — but just wait, I’ll be back out there, soon, cycling to the train station!

Feminism in Technology and Cycling

I’ve wanted to write this for a long time, but got rather scared about posting anything about feminism after the recent “It’s about ethics in games journalism” nonsense.

The scariest thing is that I have friends who genuinely believe that it really WAS about ethics in games journalism, not about keeping minorities out of their exclusive club.

Feminism in Technology

I’m in the middle of this really great Venn diagram, so I’ve started seeing a lot of similarities in campaigning and threats. I write software user manuals, so I consider myself a part of the software industry. I also commute by bike (at least, I did until pregnancy made me take a break) and have gotten involved in cycle campaigning.

Venn diagram of cyclist, female, and tech

As a woman in technology and as a cyclist on the roads, I’m a minority. And, it turns out, minorities don’t really get treated fairly…

Physical threats

Inpatient drivers and catcallers don’t necessarily realise just how threatening they are. What they do have in common is that they’re unashamedly using their position of power.

It’s unlikely that a car that’s driving too close to a cyclist is going to be injured. The car can, then, be used as a tool to threaten a cyclist with little risk to the driver. Likewise, a catcaller is unlikely to catcall if they think there’s any risk that the target would harm them back.

Victim Blaming

When I come home, upset because my life has again been risked on the roads, the reaction from friends and family is rarely “I wish people were more considerate of you! The police should do something about this!” Instead, it’s questions of “Were you wearing high-vis?”, “Were you wearing a helmet?”, “Why don’t you just stop cycling if it’s making you so miserable?”. It doesn’t matter what someone is wearing – I should not be punished with assault just because I’m not wearing what people want me to wear.

It makes me angry, deeply angry, that friends and family should push me to give up something I love. I am not the one doing wrong here, I am not the one who needs to change. By advising me to give up cycling, they are implying that it is my own fault that my life is risked, not those other people who are breaking rules and threatening me.

Any sensible person wouldn’t throw themself into the path of a vehicle that would injure injure them. People on bikes aren’t the ones who wield the strength and power.

Women for years have been fighting for the right to wear what they want and to walk where they want without fear of assault.

I will cycle in a short skirt without a helmet– Why should that mean I’m asking for harassment?

Anti-Feminism and Vehicular Cyclists

I have a friend who’s a staunch vehicular cyclist. The reasoning being “I have the right to be in the centre of this lane, the motorists are obligated to slow down and wait until it’s safe to pass. There’s no problem here, just people not following the rules. Enforce the rules and you won’t need to take away road space just for cyclists.

This same friend of mine thinks it’s wrong to have women-only groups in the technology sector, on the grounds that it’s unfair to men.

I can’t argue with the “fairness” of it. Yes, it’s unfair to exclude men, but it’s also unfair that the minority groups such as women and people of colour are forced to endure marginalisation and harassment on a daily basis and we rather need to have a support group lest we leave the industry altogether!

Yes, it’s all well and good saying that enforcing the rules will make the roads a friendlier place — but people are only human and they will use the power that they have. They’ll do reckless things because they aren’t always aware of how much more power they have than the more vulnerable road users.

Where resources go

There is a problem with allocation of resources in both trying to get women into STEM and get more people onto bikes. There’s a huge number of campaigners all crying out for mostly the same things, but those with the money keep insisting on spending it elsewhere.

There’s a huge number of big software companies who are throwing money at schools to try to get kids into software development and especially the young girls. They should be spending money at trying to retain the few women they have already in the field which would, in turn, provide role models for the young girls they’re so desperate to get in. This would involve upsetting some folk (like those who think it’s unfair to have women-only groups) but it would benefit everyone in the long run if there was a more diverse industry.

Something similar happens with money to get people onto bikes . The politicians keep throwing money at the “easy solution” that won’t upset the motoring lobby– cycle training. But training won’t get people to STAY on their bikes. To get people onto their bikes and to get them to stay, there needs to be infrastructure changes. They’re expensive, and it requires ruffling some feathers, but it’ll benefit everyone in the long run.

 Cultural Change

There needs to be a cultural shift, there’s no question about that. Changing our society to make women equal, truly equal, is not just about paying them the same and letting them take time out for families. It’s also accepting fathers as caregivers, too. It’s about no one doing a double-take when you say that your closest female friend is a software developer, or that your father is a nurse;  anyone should be able do the work that they want to do.

On our roads, it’s about making the groups of such disparate vulnerability all equally safe. This means giving them their own space. This means enabling people to choose which mode of transport suits them best, because it is most convenient or pleasurable, not because it is most safe.

A Pedestrian for Pedal on Parliament

Every road user is a pedestrian at some point, even if you’re walking from your car parking space to the cinema. I spent years walking around Edinburgh and, now, walking around Falkirk as my primary form of transportation. Being a pedestrian should be easy, just a matter of walking along to your destination! Unfortunately, it’s not…

Too frequently, the pavements are not a safe place for those on foot. It’s bad enough that pavements are often potholed just as badly as the roads and are clutted with street furniture but, on particularly scary roads or where the cycle paths aren’t properly linked up, many cyclists will make use of the pavement (often considerately, but not always)[1]. Then, to make matters worse, many councils have been re-allocating half of already-narrow pavements for the use of bicycles! It’s hard to tell anymore which pavements are for the sole use of pedestrians and which ones we need to share. What is a walker to do?

This year, I will be joining Pedal on Parliament as a pedestrian — because I know that improving our roads for the benefit of bicycles will also benefit the roads for pedestrians like me. Here’s how:

  • Where there are fewer cars, there is less overall risk of serious injury, given that collisions between bicycles and pedestrians are less likely to cause serious injury than collisions between pedestrians and cars! [2]
  • Where there is safe, separated infrastructure for bicycles that are properly joined up to other cycle paths, cyclists will not feel the need to use the pavements to stay safe or join up their broken journeys. [3]
  • Where motorised traffic is calmed, reduced, or removed to make space for cycling, it makes a more pleasant atmosphere for pedestrians, too. The air is cleaner and it’s quieter. [4]

So write to your politicians and then join me at Pedal on Parliament 25th April 2015 — I’ll bring my walking shoes, you should too!

[1] http://www.telegraph.co.uk/news/uknews/road-and-rail-transport/10577958/Let-cyclists-go-on-pavements-if-roads-are-dangerous-minister-tells-police.html
[2] http://road.cc/content/news/109269-are-drivers-and-cyclists-just-dangerous-pedestrians
[3] http://road.cc/content/news/126192-get-cyclists-pavement-build-better-bike-lanes-washington-dc-finds
[4] http://www.bikehub.co.uk/news/health-and-fitness/more-people-on-bikes-and-fewer-people-in-cars-is-key-to-improving-air-quality-says-new-study/

Waverley Fortress Whinge

I’m in a bad mood and I have a blog. So here, have a whinge.

I’m not the only one thinking of the changes to Waverley Station are really just turning it into a fortress. Beyond how annoying it is to have to walk behind slow pedestrians on a very narrow pedestrian walkway, I’m fully expecting that there’s going to be an injury as a result of the location of the barriers at the top of the walkway.

I was regularly commuting from the North end of town when the conversion from Train Station to Fortress commenced. I started my coast down Waverley Bridge and found, out of nowhere, that there was a barrier preventing me from continuing to coast down the North Ramp into the station. I stopped abruptly at the barrier, dismounted and walked, certain there was a mistake — they had only JUST made North Ramp a dedicated cycle space! I wondered what they were up to that they’d need to temporarily close the ramp. Ooh, were they going to actually paint a cycle lane to let the pedestrians know that they ought not stand there and smoke? No.The next day was when I’d spotted the signs that said that this was going to be the way it is until further notice. No official explanation why. I tweeted Network Rail to ask, no response. I emailed to ask why they had to close it to cyclists, no response. I know, now, that many other cyclists also emailed and wrote letters, but still no response. Sure, we’ve got theories, but none that explain the blanket ban.

Time passes, annoyance increases.

I’m now commuting from the South end of town, and could much more easily enter the station from the Market Street entrance…. But the escalators are a bit too steep to take the bike down, the bike is a bit heavy for carrying down two flights of stairs, and the lifts are slow. Besides which, there’s road works on Market Street so I need to get past the temporary lights, navigate around the potholes, and squeeze between the cones to dismount in the first place. It’s a stressful way to end an otherwise lovely journey.

I tried going North up Waverley Bridge and turning right down the South Ramp. I wait for traffic and, as soon as it’s clear, I turn across traffic — to find there’s nowhere safe to dismount. The orange-and-white barriers that they’ve installed more recently are flush with the kerb against a moving lane of traffic. So traffic needs to be clear enough not just for me to cross traffic, but for me to cross traffic, slow to a stop, dismount, and get onto the pavement. Sure, there’s a bit of paint on the road to say that the kerb is meant to come out further than it physically does, but tell that to a taxi that’s just pulled out and is skirting the kerb closely because there’s a bus coming the opposite direction.

I had a word with the Network Rail staff in the office to ask if they could, at VERY least, move the orange-and-white barriers further back so I at least had somewhere to dismount. The fellow at the desk looked genuinely surprised that he’d not considered cyclists needing to dismount somewhere, to transition from being a vehicle to being a pedestrian on their stupidly narrow ramp footways. He said he’d speak to his manager about it. The next day, one of blocks forming the barrier at the top of each ramp was moved to the side, giving me somewhere to cycle to where I could dismount. By the following day it looked like the barrier blocks had been moved back.

Seriously. Waverley Station planners, whoever you may be, this is ridiculous and dangerous — fix it.

The Alternative Dawn Alarm

Daylight lamps are expensive. I had been saying for years that I was going to buy one but I hadn’t quite gotten around to it. I used one, once, when I had a flatmate who kept his in the communal kitchen /livingroom so I know what a difference they can make.

After I moved out, I’d researched them to decide which to buy and came across dawn simulators like the Lumie bodyclock alarm clock. These are designed to make your body “see” a sunrise at about the time your alarm clock would go off, so that you wake up more slowly and naturally (rather than being jolted out of sleep, mid-REM, by an alarm clock buzzer).

In the Scottish summertime, I keep the curtains and blinds closed tight, trying to keep out the 11pm sunset and 5am sunrise (it’s too bright for me to easily fall asleep and stay asleep). In the winter, those handful of daylight hours are just not enough for me to ever feel awake. Dawn simulators, unlike just keeping the curtains open, switch on at the same time every morning — so, despite the seasonal differences, I can keep the curtains closed tight and the room dark and I’ll still have a sunrise for when I need to wake up for work.

I didn’t manage to buy one back then, because they were all too expensive (and I was a poor student/graduate). By the time I had enough money that I could feel comfortable investing in one, I’d already ended up with a much, much cheaper alternative…

A few years ago (has it really been a few years already?!), I’d seen a Lifehacker article about under-bed lighting. I showed it to my partner who thought it was a nifty idea so we plugged a multi-colour IKEA strip light in under our Malm bed and set it to red so that it would be dark enough that it would be only just visible at night.

A short time later, my partner and I had watched a BBC Horizon episode on how humans perceive colours. It turns out that blue light makes your brain think it’s dawn! We put two-and-two together, switched our LED lights from red to blue, and plugged the whole thing into an outlet timer. Voilà! Instant daylight alarm clock!

Our current setup doesn’t have the lights under our bed, because our current bedroom is too small and the light doesn’t bounce around the room enough to wake us up. Instead, the light is behind the dresser, bounces off the semi-gloss painted walls, and lights up the whole far end of the bedroom.

Blue LED lights reflecting light off a painted wall
Showing the current light and outlet timer setup

It’s not the most ideal setup, because some mornings the faint “click” sound made by the outlet timer switching on wakes me up (if I’m in a particularly light sleep at the time), but it’s a lot better than waking up to a buzzer every day! We’ve been waking up to this for a few years now and it works a treat. About 15 minutes after the light turns on, the radio also switches on using a timer (tuned in to the peaceful classical music of BBC Radio 3) — but we’re usually already awake by then so we can enjoy the warmth of bed whilst we listen to the news headlines.

We have it set so that it doesn’t switch on at the weekends, but we barely sleep in more than 30 minutes, now, because our bodies have gotten so accustomed to waking up at a certain time. When the clocks changed, though, it only took us a few days of gently waking up earlier than we’d like before we were on the new schedule. I’ve never been a morning person, but I can wake up now without the grumpyness and anger at the alarm clock. I may still be tired if I haven’t gotten enough sleep, but at least I won’t be groggy.

Someday I’ll get a daylight lamp, to leave in the livingroom to have some “sunshine” in the winter evenings but, for now, this is enough.

Why I Pedalled on Parliament

Yesterday was the third Pedal on Parliament. This year, rather than simply riding with the crowd, I heeded the call to arms and found myself marshalling at St. Mary’s Street, helping slow down (and stop) cyclists briefly as the lovely traffic police stopped cross-traffic and removed the barriers.

I was told that the only problem with marshalling down the road is that you don’t get the fun of joining in ringing a bike bell with everyone else or exhilaration of being part of the crowd moving down the Royal Mile — but I had the distinct pleasure of seeing every single cyclist pass by me on their way to the Scottish Parliament.

It’s seeing the crowd there that really drove home why I wanted to be there, why I needed to help —

I’m not alone on these streets.

There are hundreds of us, thousands of us. We are men, women, and children. We are families with wee bairns on balance bikes, we are teens with stereos, we are lovely ladies and men in lycra.

Some of us came in our Sunday best and some came out out in our most casual of jeans. Some of us wore fluorescent jackets and helmets, some wore just helmets, some wore nothing special at all. Some of us rode recumbants, tandems, racing bikes, mountain bikes, folders, bikes with trailers and tagalongs, and some of us walked.

And we were all there, together, showing that we, people of all ages and abilities, have one thing in common:

We want Scotland to be a cycle-friendly country. And we want it now.

If you want to support Pedal on Parliament, please contact your MP, MSP or local counsellor and tell them that you want to see more! You can also donate to Pedal on Parliament through the PayPal link on their website.

Reaching out

On the 10 July 2013, I gave a presentation at Edinburgh Tech Meetup on documentation. The audience was a room full of software engineers – some were freelance, some were managers of small startups, some were students who hadn’t entered industry yet. The video and slides are available on my presentations page. After my presentation, I was contacted by the editor for Communicator, the journal for the Institute of Scientific and Technical Communicators (ISTC), and asked if I would write an article on the topic.

I wrote the following article for the Winter 2013 edition of Communicator.

Reaching out

Not everyone likes writing documentation. Denise Marshall explains to developers how to stop worrying and love the document.

In my experience, it is the rare software developer who enjoys writing documentation. I have become accustomed to looks of bafflement from software developer friends. Their experience is the polar opposite of my own: they find it profoundly frustrating.

One of the regular events that I attend is Edinburgh Tech Meetup. It’s primarily a networking event for freelance software engineers, software startup founders, and many others who are generally interested in computing. One evening every month, the group meets to listen to two presentations and spend several hours in discussion. While I usually find the talks interesting, my primary interest is meeting with other members in the software and technology community. It was in a conversation with a developer at one of these evenings that I realised that documentation is getting a bad name among those who could be its staunchest allies.

“What can I say to my boss to convince him to hire a technical communicator?”

As I conversed with the developer, I heard a story that I’d realised I’d heard several times from different software engineers. There seems to be a level of wishful thinking present in the software world that says that the software product should be obvious enough to the users that documentation simply isn’t necessary. Likewise, the code should be obvious enough to anyone who’s reading the source code that a couple of comments in the source is sufficient to understand how all the sources work together. Of course, most developers are aware that this is a pipe dream.

In reality, documentation needs to be available alongside the product. For the work that I do, my readers often don’t refer to the documentation except in their hour of need, either when the workflow isn’t obvious and they cannot find the solution themselves or when they want confirmation that what they’re about to do is correct. For my documentation to be useful, it needs to be thorough enough that they can find the answer to their question and clear enough that they can understand the solution.

The organisations that these developers work for rely on them to document their work. This makes sense because the developers know what the software is meant to do (they have their formal requirements, at least) and they know how to use it. It follows, then, that it would take the developers little time to write up what they’ve done, because they’re the ones in the best position to know what they’ve done.

But these same developers have deadlines that they must meet to deliver the software and are often too pressed to make time for documentation. With documentation included in the requirement, the organisation’s projects can fall behind. The inevitable cycle would lead to someone in management deciding to hire another developer to take up the slack. The existing developers don’t know how to write documentation and get frustrated that more and more of their time is wasted (their words) on documenting their code, rather than being spent on writing good code. Sadly, the blame is placed on the documentation for putting them behind schedule. To add to the feeling of frustration, the developers I speak to generally feel that they weren’t documenting well, because they didn’t know what they were doing. And the new developer needed to be brought up-to-speed, further slowing the development process. I offered the best advice I could: “Convince your manager to hire a technical communicator. They’d happily do the documentation part of the process.” Then would come the inevitable reply: “My manager says we can’t afford a technical communicator. Could you give me some pointers on how to get started?”

What could help their experience with documentation?

I set about creating a primer on producing documentation for those developers at Edinburgh TechMeetup who had no choice but to provide the documentation because their companies could not take on a technical communicator. I could, at the same time, provide those employers who had never considered hiring a technical communicator with an argument for considering one in the future. I knew that the audience I would have in front of me would see documentation as something unpleasant so I wanted them to know that I knew where they were coming from.

A primer on documentation

I’m fairly certain that any reader of Communicator will know how best to communicate information to their audience – it probably comes as second nature – but, for the uninitiated, it can be a baffling world of text editors, words, and images. I laid down the basics that a non-technical communicator would need to produce a minimum standard of documentation:

  1. Know your audience. If you know who your audience is, then the style and content of your documentation often becomes obvious. For example, if you are explaining to a developer how to use the different functions of an API, then an API reference guide makes sense. If you want to get new hires up to speed quickly then a wiki with some overview information might be sufficient. Do you need to explain how to use software to groups of pre-literate children? Pictures might be best.
  2. Create a structure. This can sometimes be hard but I find that, in the absence of a strict template, it’s often made easier by writing each idea into separate topics on notecards. These notecards can then be grouped, arranged, and rearranged until they make the most logical sense. This also encourages topic-based documentation. (I also reassured them that, after they’ve got a basic outline, they can save it as a template to simply fill in the next time they needed it.)
  3. Find your style. Be Consistent and Be Clear. For example, there are many ways to write ‘email’ (Email, E-mail, email, e-mail, eMail, etc), but as long as you pick one and stick to it, you’ll never have to wonder again which is the correct one. Likewise, phrases such as ‘Enter text into the text field’ should be made consistent (other options might include ‘Type text in the field’, ‘Write text in the box’, and ‘Fill in the text’). If you write the phrases consistently, the perceived quality of the documentation increases and the technical communicator can move more confidently into other areas of the writing.It’s also important to avoid ambiguous language. While it can sometimes be hard to know if your sentences will be misread (that’s where asking someone else to review it is useful), it’s easy to avoid ambiguous words. A list of words that should be avoided can be added to a personal dictionary in your preferred word processor. At the top of my current list are ‘since’ (when you can use ‘because’), ‘once’ (when you can use ‘after’), and ‘appears’ (instead, use ‘opens’ or ‘is displayed’).
  4. Consider graphics. Graphics should be avoided unless you’re absolutely sure that you need them. This reduces file sizes, reduces translation costs, and means that you don’t need to update them with every small UI change. There are times when graphics are good, such as when you’re drawing a diagram of system architecture and it’s important to consider your audience when deciding the necessity of graphics – some audiences might genuinely require a screenshot of every single page in a Wizard.

And that was it. I tried to keep the rules as simple as possible, in the hope that some of it would stick. If one developer could, at the end, decide who their audience was, organise their ideas, and be consistent throughout, then I knew it was worth it. But I wasn’t quite done yet.

Is it worth hiring a technical communicator?

After explaining to an entire room of developers how to approach technical documentation, I asked them the question that was at the heart of the reason that I delivered the presentation: “Would you rather be writing documentation than coding?” The only people in the room who raised their hands were, like me, technical communicators. Every developer I’ve ever worked with has expressed how much easier we make their lives, because we know how to put all the things they know into words on paper. Unfortunately, many in the audience hadn’t had the opportunity to work with a technical communicator. So I laid it out as succinctly as I could:

Hire a technical communicator and the developers have more time to code. Yes, they still spend time on documentation because they need to explain things to the technical communicator, but it is a very small fraction of time compared to what they would be spending otherwise. In addition to that, the technical communicator would be more efficient because they would know how to write.

Reaching out

The most surprising thing that happened, at the end of the talk, was that a developer approached me and confessed that he didn’t think he was going to like my talk. He’d done documentation before and, like the others I’d spoken to, didn’t like it and didn’t really see much use for it. He told me that he was inspired to start documenting the project he was working on. Another developer told me that he’d never heard of technical communicators and had a friend who would probably love the job and asked if there were any training courses available.

I hope this article has helped you realise that we don’t need to limit our audience to the readers of our documentation.

Burley Travoy Pack Mule

I walked up to the counter at the local grocery store, my shopping trolly full nearly to the brim. I set the separator down at the end of the belt, to make it stop moving. I then proceeded to unload the trolley while the cashier dealt with the previous customer who was still bagging her groceries. I put the large, heavy things closest to the till, the light bread and eggs near the end of the belt, and left the giant bag of pasta to the very end. By the time I was finished, the previous customer had left and the cashier turned his attention to me:
“Do you want help packing?”

It’s not my favourite question, for many reasons, but I answered as I always do when I have my bicycle trailer with me:
“No, it’s ok. I’ll just fit it all in this bag.”

At this point, of course, the trailer was still collapsed and in the trolley. It didn’t look like much and it certainly didn’t look like it’d fit a trolley worth of groceries into it, once full. The cashier looked at me, very puzzled. “It’s a big bag. I swear, I’ll unfold it, it’ll fit.” He nodded in a way that made it clear that he didn’t believe me but he was going to humour me because I am a paying customer.

Item by item, I packed the bag. Heavy items went to the bottom, the lighter and crushable things on top. A grocery Tetris game. Sure enough, I was able to pack it all into the bag, minus the huge bag of pasta that I lashed to the top of the trailer. The look of confusion on the cashier’s face melted away to boredom. Can’t impress everyone.

Burley Travoy trailer full of groceries
Bike trailer full of groceries, en-route home

I got it home and took a picture of all of it unloaded. About two weeks of food for me and my other half — about half what would fit in the boot of our old Renault Clio but easily five or six times what I once carried in a rucksack.

Groceries spread across the dining table
The amount of groceries that can fit into the Burley Travoy bike trailer

People keep telling me that they can’t really carry much when they’re cycling — but that’s because they keep thinking of their bike as only what they can fit in their rucksack. But there’s a whole world out there of pannier bags and trailers that’ll completely change how you can use your bike. Oh, and the bike AND the trailer fit in that tiny space under the stairs when I’m done.

NaNoWriMo 2013

This is the first year that I’ve joined National Novel Writers Month (NaNoWriMo). For those who are unfamiliar with NaNoWriMo, it is a challenge for participants to write a 50,000 word novel in only the 30 days of November. I don’t write much fiction, preferrering the structure, regularity, and utter lack-of-frills in technical writing.

Not to say that I haven’t tried “creative writing”. When I was still in school, I would often embark upon a short story, get about two thousands words into it, then give up rather unceremoniously. I thoroughly enjoyed creating the world, creating characters, but I struggled with finding a sound plot and the dialogue that I attempted was always dire.

I’ve had many friends get to the end of NaNoWriMo and tell me how liberating it was, quieting their inner editor to produce volume over quality. They wrote without regard to how well it would be written and it let them explore their writing in ways they’d never done before. There was also the satisfaction of having completed such a challenge, though silly it could be from an outsider’s perspective. The writers equivalent of running a marathon for no other reason than just to say you’ve done it once. I’d considered it in years past but something always came up – university exams, moving house, getting married – so I never tried. But this year, I had no excuses….

The first week of this year’s NaNoWriMo was exciting. I started out with dialogue and used that to create my characters. I interspersed it with some scene setting and sprinkled in some intruigue, hoping that any of it would lead to a plot. By the end of the first week, I had just over 10,000 words and no fewer than six interesting characters. Unfortunately, the story had gone nowhere.

It’s now Day 16 and I’m approximately 1000 words behind where I ought to be for this time on this day. I fell behind during what is referred to as the “week 2 blues”. I’d experienced something similar before – my company offerered an intensive one month training course (6.5 hours of lecture a day, 5 days a week, 3.5 weeks). The beginning of the second week was painful and all I wanted to do was give it a rest. For this NaNoWriMo, writing was like pulling teeth. I was uninspired and found myself wishing I was reading the Metro on the train instead of standing with my laptop propped up on the bicycle rack. I never stopped writing but I spent so much time staring at the screen that I’d fallen 2500 words behind.

Someone recommended that I introduce a natural disaster to shake the characters out of their lull – another friend recommended a fire. I thought I’d run with it, wrote that a neighbour’s house was set on fire, and let the characters react to that. Somehow, a plot bloomed. I found myself geting angry when the train stopped at my station and I had to shut down the computer to cycle home. I’d had a series of evening after-work outings and really ought to have been sleeping as soon as I got in, but I found myself laying awake in bed, forcing myself not to get out of bed to grab the laptop.

If in doubt, put your characters in a fire. If you really like them, then they’ll easily find a way to escape. If you don’t like them, then maybe their clever escape will redeem them.

15 days down, 15 days to go… [to be continued]

The Techaddicted Guide to Documentation

I’m forever telling my developer friends that “Documentation is not a dirty word!”. But, for most of them, documentation is that thing their managers tell them they need to do, that thing that gets in the way of coding, that thing that takes forever because they don’t know how to do it and the don’t want to do it. These same friends keep asking me “We’re falling behind schedule at work and so my boss wants to hire another developer — I suggested hiring a writer but apparently we don’t have the budget for that! How do I convince management that it’s worthwhile to hire a writer?!” I’ve previously written a blog post about this, but I realise it’s not enough.

So I put together a presentation that addresses two main points:

  1. How to write documentation – Because sometimes documentation is inescapable and it doesn’t need to always be painful.
  2. How to justify hiring a technical writer – Lacking hard statistics, but with a story and diagram.

I presented this at Tech Meetup Edinburgh back in July. You can watch my presentation below (30min, including questions) or you can just flick through the slides yourself (View Slides).

Denise Marshall talks about Documentation from TechMeetup on Vimeo.

NOTE: Most of my images are from XKCD. See http://xkcd.com/license.html for license info.

Words to Avoid

After my presentation, I got a few requests to share my list of Words-to-Avoid

That list can really be broken down into two categories:

  1. Ambiguous words – they have more than one meaning and both meanings are frequently used. But one way of using the word can be easily replaced with another, non-ambiguous word. Sometimes you need to use a word that has multiple meanings, but if you consistently use it to only ever mean one thing, then that goes a long way to helping keep things clear.
  2. Warning words – words that should warn you that your writing is in the wrong tense, wrong tone, or something else un-good.#

Lets start with the ambiguous words….

Ambiguous Words

Once

Once should only ever be used to mean one time. You do something only once. Though once upon a time doesn’t really belong in serious documentation. Most of the time, the word after is a perfect drop-in replacement for the incorrect usage of once.

Hint: If you use once at the start of the sentence, it’s probably incorrect. Sometimes it’ll be in the middle of the sentence. Every time you use the word once, think to yourself if you can replace once with after and keep the meaning of the sentence – if you can, then do it.

Good: Click the button once to save your document.
Bad: Once you’ve clicked the button,  the system restarts.

Replace bad of once with after

Correction: After you’ve clicked the button, the system restarts.

Since

Since is commonly used in conversational English to mean because. For example, “Since I don’t like peppers, I always have to pick them off of the veggie pizza” is fine for explaining that I am picking peppers off my pizza because I don’t like them. But since also serves as a great word for describing “time that has elapsed between this previous event and now” quite succinctly, such as in “I haven’t eaten since breakfast”. Because since can easily be replaced by because in some cases, the because sense of since should be replaced with because to make the usage of since in the temporal as unambiguous as possible.

Good: If you have not restarted your system since installing updates, do so now.
Bad: The updates have not been fully installed since you have not yet restarted your computer.

Replace bad since with because

Correction: The updates have not been fully installed because you have not yet restarted your computer.

May/Might

May and might suffer from the same problem — are you trying to say that it is possible that something has the ability to happen or are you saying that something has permission to do something. It’s like being back in school again and Miss is telling you “Yes, you can go to the toilet but no, you may not”.

Just forget about may and might and your Miss who’s making you hold it until lunchtime. Just use can and could instead. But when would you use which?

  • can for permission
  • could for ability

Good: You can create a new customer account.
Good: The system could crash if you do not create the order using the wizard.
Bad: You may create a new customer account. (Do you mean “You have permission to”? “You have the ability to”? “There is a possibility that you want to”? etc. So many different meanings!)
Bad: The system might crash if you do not create the order using the wizard.

Warning Words

Will

If you’re using the word will, it means you’ve slipped into future tense. Stay in present tense.

Good: The report opens.
Bad: The report will open.

Please

You don’t need to be nice in serious documentation.  Conversational writing can work for you, but be careful of humour in technical documents. Humour is difficult to read and is even more difficult to translate. If you’re including words like please, you may be slipping into other casual language. In technical documents, just stick to the facts.

Please implies that the reader does not need to do what you’re going to ask them to do and that you don’t think they’ll like to do it – you just need to tell them do do it.

Should

Nothing should happen. Either it can happen or it does happen.