The problem with “It’s self-documenting” is that there are inevitably questions about what it says, and there’s no additional resources to pull from.
I’m just this guy, you know. Except on Lemmy.
The problem with “It’s self-documenting” is that there are inevitably questions about what it says, and there’s no additional resources to pull from.
Totally agree. And I’d argue that we don’t even need technical writers. Even if all people do is correct grammar and spelling mistakes it would be helpful, let alone actually writing docs. It’s one of the easiest ways non-technical folks can get involved with open source projects.
If you know your weakness is writing documentation, please hire a technical writer.
I’m really thankful that I had a great English teacher in high school, and that my degree required a technical writing class. Being able to write a coherent email got me further in my career than the technical stuff I learned in college.
It’s also why the humanities are important. Stemlords who brag about not doing literature classes write terrible documentation.
You have to assume some level of end user knowledge, otherwise every piece of documentation would start with “What a computer does” and “How to turn your computer on.”
I’ve found the best practice is to list your assumptions at the top of the article with links to more detailed instructions.
You know what? I’m gonna left even harder.
I’m okay with that, actually. Start with teaching kids in preschool that if they find a gun they shouldn’t touch it and should tell an adult, impressing upon kids the danger of guns, and finally ending with marksmanship training.
Then cut the military budget by 90%.
If we’re gonna have a rifle behind every blade of grass they should be crack shots.
Gee it’s almost like we should make sure folks know about how to handle firearms without relying on their own curiosity
You can’t automate away all the unpleasant and technical bits.
But it’s our job to try
Yeah! There’s a lot more to open source projects than code. Even if all you do is edit the docs for punctuation and spelling mistakes you’re helping.
It’s not pride, it’s just that I know how to use it really well and that makes it easy for me to use.
But it’s really only for viewing files on another system over SSH. For local work I use Sublime Text