4 ms·
> so you're stuck with technicians that only have repair manuals, along with spare parts of everything Tell me more about how people hate writing documentation
by drdeadringer 5y ago
> so you're stuck with technicians that only have repair manuals, along with spare parts of everything
Tell me more about how people hate writing documentation, and then tell me how they can't shut the fuck up about not having it when they need it.
This is a peeve of mine.
What do you expect?
- bawolff 5y agoWhat's so surprising about it? I hate cleaning my apt but also hate when its dirty. There's no big contradiction here.
- a_t48 5y agoIf only I could pay someone to write the documentation for me.
- sharken 5y agoYou would still have to explain to someone what it is that should be documented. A better approach is to learn just enough to do it yourself, but it's not easy to document things well. I like to think about documentation like this: Without it your work will be almost wasted as nobody can make use of it. That helps a bit :)
- a_t48 5y agoThus the "if only" - I can pay someone else to clean my place pretty well, but I can't really pay someone to take knowledge out of my head.
- totetsu 5y agoLast time I cleaned my apt I managed to delete my grub conf somehow and had to spend the day learning to manually mount an encrypted zfs pool. Luckily I have some etc keeper thing that keeps a git log of all changes to my conf files so I could restore it.
- seangrogg 5y agoI do think it's a bit telling that we have a lot of automated software that exists to help us style our code, but there doesn't seem to be nearly as much investment in documenting code. Simple things like a linter that yells at you if a class has an undocumented method would probably at least be a step in the right direction. People may complain that it would lead to overdocumentation but I'd argue that it's probably better than underdocumentation. Even something as simple as providing a warning when there appears to be an long code block without documentation would probably be a step in a decent direction. What seems trivial and obvious today likely will not in a matter of weeks - and it generally just gets worse from there.
- the_duke 5y agoIn Rust you can just add `#![deny(missing_docs)]` to your code and compilation will fail if you have any undocumented items. Of course that can lead to developers just adding a single line comment with the name of the type ... but it's still a nice feature.
- seangrogg 5y agoThat's actually super cool; I wish I had more reasons to reach for Rust on a regular basis but this is definitely something I'll keep in mind should I ever get the opportunity to use Rust in any capacity.
- HeyLaughingBoy 5y agoVisual Studio nags you if public methods and properties aren't documented. It's not a panacea, in fact it's easy to work around but at least they're trying. IME, the only thing that works is to attack it from a Project level: make usable documentation (needs a review before being signed off) a deliverable or the project isn't done.
- cblum 5y ago> Tell me more about how people hate writing documentation The thing is, I don't this happens in isolation. At least not for me. I hate writing documentation because time is not allotted for it. So I have to rush it, and in the process I feel like I'm doing a poor job, which is demoralizing. I'm gonna dread it next time I have to do it.