Skip to main content
NEW CYLANDIA Public Library

izzy's documentation manifesto

by izzy kestrel

confused clipart woman doesn't understand why she was given a packet of paper with code snippets on the first day of her new programming job

in another life i had a shitty programming job and one of my most enduring memories of it was the first week where i had to set up my dev environment. it was a massive list of instructions, starting with a full install of Windows 7 on a virtual machine, followed by a ton of program installs and other arcane bits of configuration that took me at least 2 full work days to complete.

once i had finished, i realized i had done something wrong and had to do the whole process over again.

documentation is challenging to write bc you can never entirely know what kind of existing knowledge your audience is bringing. you don't want to be too technical and alienate less experienced readers, but on the other extreme, giving a dry step-by-step can leave out too much context and make it harder to troubleshoot when things inevitably go wrong, as the user now lacks the understanding to Simply Google the solution.

i have a couple of soft goals for tutorials written for the Library of Cylandia, which will likely be met with varying degrees of success:

in short: the best documentation is written with empathy for the reader. don't write a hazing ritual or write to impress them with your incredible and advanced knowledge of the subject. write like a person and write like you're talking to a good friend. do some swears and crack a fucking joke or two. write in all lowercase bc you dated a girl once who only texted in lowercase and only capitalize stuff when it's Feels Important or Funny to do so.

smiling wizard emerges from colliding keyholes

anyway, that's what i'd ask of my fellow Cylandians, but also i'm not in charge or anything so they can also feel free to ignore all of it and even write their own manifesto for how they prefer to do things. this is ultimately just my way of Establishing A Baseline Vibe and giving readers a nice starting foothold before beginning their ascent up Tutorial Mountain.

or maybe Tutorial Rock Wall is more appropriate. idk i've only done like indoor rock climbing at a rec center where there's soft mats and lots of safety equipment tethered to your body. that's more the vibe i guess - if you fall, i will do my best to catch you (unless i'm checking my phone or something, nobody's perfect)

actual photo of me, age 27, rock climbing to impress aforementioned Girl Who Only Texts In Lowercase. mere moments before The Accident