Comments by "Winnetou17" (@Winnetou17) on "Is Too Much Documentation Bad? (Is No Documentation OK?)" video.

  1. Besides having well structured, well done etc documentation like other said, there's one more thing: context. Just saying is "having documentation" is too general. Does it mean a man page ? --help option ? A long web page ? A wiki ? A series of tutorials ? These all are good resources, but for different contexts. So, for command line programs, a man page is required. Unless I'm mistaken "man" comes from "manual". A manual has to be detailed and, as best as possible, complete. So I'd say that a massive 100-page long man page for find is ok. But, staying on the command line programs, you also, many times, only need to check some flags, get some examples and things like that. That's were something like --help or maybe even more flags (maybe --examples?) come to mind/help. You should have all the details in the man page, starting with how to get these quicker, simpler bits of help, so you can type your command in less than 1 minute and go on continue what you're working on. For complex programs (like Blender, or even ffmpeg) I think that a wiki and a series of tutorials is also needed. Especially if using images or video or audio would simplify the teaching/education (those cases where an image is worth 1000 words). For source code, yeah documentation is good. Since I'm a programmer myself, the problem is usually that very few people bother writing documentation (because it's hard, tedious and excessively boring. Few, few people have the drive or talent or passion to write documentation). However, a bit of suckless mentality does good here. The source code should be as easy to understand as possible (of course, without compromising quality) and only then, when needed (like explaining WHY a function or some line is needed, or what a flag or something like that might mean in an external context) the documentation should be written, usually trying to be as concise as possible. Back to contexts, installing an operating system is not like simply running a command to find all your php files. You do need to understand what is happening. So, while reading most of the stuff in the Arch or Gentoo wiki will take days, you will be better off it, have much less (potential) headaches from the mistakes that you didn't made, that could've also been spread to those who you asked for help. Since I mentioned, maybe everywhere where there's documentation, the scope of it should be mentioned too. Like a man page could state that it's a long read, if you need a quick nudge to get over your work, check these help/examples. If you do know that you want a complex case then you know you'll have to spend more time to read the man page. A blender wiki could state that learning it will take probably months and that you should start with understanding some terminology and flows and do some tutorials. A documentation like Arch or Gentoo install guide could (I don't remember if it does) also mention the important parts that you should know and that probably you'll need several days of reading + trying to install in a virtual machine, before achieving the install, if you've never done it before. Overall, the documentation should set the expectations of how much information it provides and how quick it is to comprehend it. Edit: and also, try to provide shorter/quicker bits of information, where it's safe to.
    2