Writing by Peter Hilton

My documentation problem

ACCU 2015 lightning talk script 2015-04-24 #documentation

ACCU 2015 lightning talk audience

‘My name is Peter and I’ve got a documentation problem. It’s been one day since my last documentation commit. I’m a programmer who actually writes documentation… and likes it.

‘I like writing code too: I spent all day on Monday writing code and it was great. That was a good day. But after a while I get cravings. I just want to crack open a nice new Markdown document and pour myself a blog post: a nice little tutorial - or maybe some user docs.

‘‘Writing helps me relax. You can even have a glass of wine at the same time, which you can’t do when you’re coding because then you have to throw the code away afterwards.

‘I used to work in an office where everyone else only wanted to write code. My boss didn’t mind if I wrote a page or two at the end of the day, but he didn’t want me doing it on company time.

‘To get through the day I started carrying this kind of hip flask that I’d use to get a quick hit. I’d sit on the toilet, where no-one could see me, and use it to write Tweets.

‘These days it’s worse, because I’ve started working from home. When I get up in the morning I don’t even get dressed before I’m at the keyboard, opening a new draft. I need at least two hundred words just to clear my head in the morning.

‘All this writing is a pretty solitary activity: it’s not like you can say ‘I’m a social writer’. Two days ago, another writer at this conference told me about what it was like when he started going to writers anonymous meetings. He said, ‘if you think programmers are loners with poor social skills, then you should see the writers’.

‘I’m actually a functioning documentaholic - it’s totally under control, and I could stop any time I wanted to. I’m still productive when I write code, and I spent all day on Monday this week coding.

‘My colleagues don’t complain either - they’ve always been happy to let me write the documentation: I write project plans, architecture overviews, installation instructions, user manuals, whatever.

‘Sometimes, my supplies get low, though. If I run out of documentation I have to make do with someone else’s leftovers. I’m ashamed to say it, but there have been times where I’ve had to resort to rewriting the product owner’s user stories. Just to get that buzz, you know.

‘And where’s all this got me? Well, the crazy thing is that my documentation habit, and slowly becoming a better writer, has benefits. I’ve ended up doing jobs with more responsibility, more money, and it’s even led to opportunities to speak at conferences. I seemed to break through some kind of ceiling in the company when I started writing commercial proposals.

‘What happened is that because I was the one writing things down, I had a lot of influence over things like software architecture, development methods and management policy.

‘There have been other opportunities too. A couple of years ago I wrote a web framework book called ‘Play for Scala’ with a couple of colleagues. They’ve got ten copies at Blackwells out there by the way. It’s so good that you should buy it even if you’re not a Scala programmer. After all, there’s this other book called something like Becoming A Better Programmer, which probably says that you should learn new languages. As for me, you don’t get much money for writing a book, but the fame is great for your self-esteem. I now think I’m awesome.

‘Now that I think about it, I don’t get why there aren’t more programmers who like writing.

‘Thank you for giving me the chance to share.’

Share on TwitterShare on LinkedIn