But rewarding. What makes it less rewarding online is we don't see the benefits. We don't hear thanks. Which we should say more often
> a lot of linux documentation comes across as barebones
One thing I try to encourage is writing documentation. People are extremely resilient to this and I'm not sure why. It has a lot of benefits. I forget what I did, it helps remind me.
But people often claim no one else will read it or it's obvious. I think we've all dealt with the frustration of dealing with undocumented code. Seen how much time it takes because of the lack of documentation. Why doesn't this encourage writing documentation?
When docs are scarce and you have access, add a little. It can be built over time. Some is better than none.
The other thing I do is write notes. I put a lot of them in my dotfiles actually. This means I keep them just text (or link for images) and these can get carried around with me. I hand them out frequently and am always happy to have others contribute or share theirs but honestly I don't know a single other person that does this. But I find it extremely helpful. I reference them all the time. Granted, they're written for me but I think more people should.
Oh boy, I had many people telling me "please teach me how to use Linux [but I do not want to read any documentation!]". It gives me PTSD whenever I see people talk about documentation. I write documentation for myself and others who give a crap. I have been downvoted here for just simply stating that I wish people were less reluctant to read documentation, so y'know.
Yeah I think you've hit on the answer of why people don't write docs: they don't want to read docs...
But docs are kinda a necessary "evil". It would be great if we could instantly download information into our brain. Instead, we have to slowly download information into our brain (and it gets faster the more you do it).
People feel too rushed. But does the rushing get us anywhere faster? It's like rushing around in your car. You feel like your going faster, but if you time yourself or watch other cars that aren't rushing, you'll observe they still are ending up at the same stoplights you are. The speed only increases your anxiety and risk of accident. It feels faster, but it really isn't in 90% of cases.
Personally, I'd rather get to my destination more calm and safe. Might cost 1-2% in time, but most of the time I'll be better at my destination if I'm relaxed. Only rush when seconds matter.
With docs are useful and you shouldn't just jump to the parts you need. The surrounding context is a force multiplier. It helps you get into the mind of the writer. It helps you guess how things get put together. It helps you understand the larger picture. All of that is helps. You don't need to read a doc front to back, but just extracting one-liners is not helpful.
But people often claim no one else will read it or it's obvious. I think we've all dealt with the frustration of dealing with undocumented code. Seen how much time it takes because of the lack of documentation. Why doesn't this encourage writing documentation?
When docs are scarce and you have access, add a little. It can be built over time. Some is better than none.
The other thing I do is write notes. I put a lot of them in my dotfiles actually. This means I keep them just text (or link for images) and these can get carried around with me. I hand them out frequently and am always happy to have others contribute or share theirs but honestly I don't know a single other person that does this. But I find it extremely helpful. I reference them all the time. Granted, they're written for me but I think more people should.