Comments by "" (@dingokidneys) on "We used to write good documentation... (w/The Taylor and Amy Show)" video.

  1. I've written so much documentation and I wasted so many hours going back over stuff, reorganising and restructuring it, re-wordsmithing to adjust the tone: I wish I'd been able to take a good course in technical writing instead of futzing about having to learn from painful experience how to communicate complex concepts to a bunch of people who really didn't want to have to know this stuff. Both my time and the users time would have been better used had I known a bit more about technical writing. You're doing a good thing.
    12
  2. That looked like you were having a hoot, which is great. Documentation is difficult and, speaking as someone who has written a lot of documentation, it's a thing that you need a lot of practice and feedback to start getting right. You need to be humble enough to accept when people tell you that it's wrong or difficult or whatever, Having a really good structure to the document that you are writing is also very important as that can make both the writing and the learning much easier.
    8
  3. When I read 'hit the enter key' and think about some of the people I've had to try to teach these concepts to, I visualise them pulling a hammer out and whacking the hell out of the keyboard. My preferred verb is 'tap' although some people might still go to the bathroom, forcibly remove a faucet, bring it back to the computer and bash it with that. Malicious compliance was a feature of some of the people I've had to deal with.
    5
  4. People these days often don't realise that proper capitalisation and punctuation is a massive guide to understanding, given that the pauses and inflections of spoken language are not present in the printed form.
    2
  5.  @Jossandoval  Man pages are certainly becoming more terrible. I've often heard of a command and gone to the man page to find a mass of arcane detail, hundreds of options and switches but nowhere is it described what the command does and what one might use it for. The name of the command doesn't give the game away either as they are often cute little in-jokes or strange mish-mashes of something else; e.g. 'exa' - wtf is that? Discovering new commands from the man page is becoming impossible.
    1
  6. $ man woman No manual entry for woman This is a fact that men have lamented forever. :)
    1