S09E08: There is no such thing as too much documentation

Last week I wrote about how I was going to pick up the work I was doing with the Civil Service LGBTQ+ network. This week I’ve spent many hours reviewing and fixing minor bugs because I didn’t write enough documentation.

I also wasted an hour of a colleague’s time because I wrote an email hastily and left out important context, which meant she did a bunch of work for me that I didn’t need and so was wasted.

So this week’s theme is how writing is important, and how a lack of documentation is actually better than bad documentation.

The way that I write is more or less. That is to say I write poetry or I write emails. Poetry is a delight, because one can write outlandish, abstract phrases like I was doorless when I met you and someone you quite fancy will find you unbelievably sexy and they can make up their own meaning, which means you can never be wrong, unless you’ve written something tremendously awful.

Abstraction and poetry are less well-suited to emails, where one must simply say I don't have a door and I would like you to install one, which admittedly may make someone who is already fond of you more attracted to you but is unlikely to spur advances from a handyman. Even if you accidentally put a xx on the end because you’re absent-minded and texting your mother at the same time.

Documenting code, particularly code that you suspect deep down will only ever be read by you, is therefore a weird place to be. There’s no feedback loop and the only person you can impact is yourself, and so frequently I don’t write enough documentation. Sooner or later this means I abandon the project, because at a certain size it’s too big to start writing documentation and it’s incomprehensible. Not this time. At the very least I know this is something someone relies on, so I’m going to do my utmost to make it better.

It also needs some kind of frontend/graphical user interface, which has not been my strength so far. So plenty of documentation there ensure I can come back to it without wanting to burn it all down and start again.

If you run a mentoring scheme, and you’re technical enough to know your way around the command line, please do try this out and let me know how you get on.

I got support this week from my senior people to run an experiment with a team in my department and GitHub Codespaces. It’s kind of new and kind of old as technology goes. GitHub offers you a virtual computer, hosted in the cloud, that’s charged by the minute. They can offer significantly more computing power than I can afford to buy, so it’s a no-brainer – why not have devs charged by the minute for an awesomely powerful computer?

The reason I say it’s kid of old is because it sort of reminds me of mainframe computing and time-sharing. Which is kind of cool – it means time is cyclical but progress is upward, so we’re all in a beautiful helix of progress.

Not a spiral. I have strong feelings about how spiral has completely taken over the meaning of its more accurate cousin helical.

In any case, with funding sorted, quantitative and qualitative data surveys standing by and the team fairly frothing at the mouth to get started, I’m really excited to kick off my first human experiment.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s