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:
- tutorials should be written for a target audience that has little to no prior gamedev experience
- if specific prior experience is required, the tutorial should open with a link to "prerequisite" resources to help get the reader up to speed (ideally, other existing posts in the Library, but external links are fine too)
- the writer should imagine what the "best" version of this resource would have been when they were starting out and be especially mindful of covering common pitfalls
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.
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)
