I find I Love MDN demeaning to technical writers. It reminds me of breaking into spontaneous applause for our courageous health workers instead of funding them properly so they can do their jobs.
Source: I Love MDN, or the cult of the free in action – QuirksBlog
Another article related to the fall of Mozilla. Back in the day we relied heavily on quirksmode.org and doing that sort of data mining, collating, writing and publishing is not easy. For a while myself helped out writing documentation for WordPress during the <.09 era and we found out for myself exactly how hard technical writing is. It’s something we’re good at and, more importantly, enjoy. We appreciate the skill, nuance, talent and even luck that goes into writing good documentation.
It is something that we complain about often on teh twitter derp corn; often using ultraviolent language cos most developers are assholes. We’ve mentioned on this here blargh of using vimwiki. Their documentation looks like… actually, not even going to bother with a screenshot because they don’t have anything on their github or wiki that actually says “Documentation”. They take the easy way out and tell you “oh run :h vimwiki in vim”.
No, fuck you, lazy assholes.
Another few great examples of technical writing gone wrong:
- Pretty much any plugins for vim. Most of them are just the same text file you’d use
:h for, except without hyperlinking.
- VirtualBox coming in with the one-page User Manual
- Nextcloud, with documentation full of gotchas that should be mentioned prior or during installation, but aren’t.
- Apple: Documentation? What’s that? Also there never was any documentation here.
I just had to use a gif for Apple. It’s that bad. Most Android apps don’t have any documentation of any kind whatsoever. Windows applications used to have documentation built-in but now they just direct you to their website, where documentation changes and disappears depending on the A-level goals for the quarter.
There are many more examples out there but these are some of the ones I can think of right now. The gist of it is this kind of thing is hard and people who do it should be paid for it, and if they’re good at it they should be paid well. If a developer doesn’t want to write proper documentation then… they should either have someone do it for them and listen to that feedback, or get their ass handed to them so they get on writing it themselves.
Going to go eat something now before the hunger makes me angrier.
