5 ms·

I think this is a good attitude. I wish that people who publish advice on writing documentation would put more emphasis on writing for people who have this att

I think this is a good attitude. I wish that people who publish advice on writing documentation would put more emphasis on writing for people who have this attitude. I see too much emphasis on providing usage examples, and on "write for a reader who is trying to get something specific done", rather than explaining the system for someone who wishes to understand it.

api 7y ago
The emphasis on getting things done vs. understanding is another manifestation of our age's extreme time poverty. People don't have time to understand anything. Add to that the fact that computing is so trendy. Take the time to learn something -- web development, mobile development, the latest trendy language -- and it won't be hip anymore in 5-10 years. As an experienced programmer I only take the time to deeply understand things that my intuition tells me will be around for a while and for which understanding is a major benefit to me. My intuition is guided by a mix of market share, speed of change in the target market, and robustness of the thing in question.
- EvanAnderson 7y ago
  It's another manifestation of the classic "it's expensive to be poor" situation. My personal struggle is with making the call re: understanding vs. getting things done compared with the return on investment. Understanding things is fun, though, and our systems are built upon enough analogy that understanding usually transfers (if only in part) to something else down the road.
  - thisisnico 7y ago
    Realistically it depends on how invested I am in the system. If it's something that I'm using all-the-time, it absolutely makes sense for me to have a deeper understanding because that understanding could save me time and give me a better perspective on why certain aspects of the system are the way they are. If it's something I use only as an auxiliary system, I don't invest as much time in understanding the system, only what the system can do for me. A prime example of understanding how to use the system, but not the system itself is e-commerce. There are 17+ year old kids making 100K+ a month with e-commerce, having no programming skills or a deep understanding of the web or computers. They are experts at the tools they use, but honestly are not "computer" people. We've abstracted e-commerce to the point that it's not even necessary to deeply understand the web, with tools that exist now (Shopify etc.)
- kqr 7y ago
  > things that my intuition tells me will be around for a while and for which understanding is a major benefit to me. My intuition is guided by a mix of market share, speed of change in the target market, and robustness of the thing in question. Don't forget about the Lindy effect! A thing that has been around a long time is likely to stay around, whereas something new is much more likely to fade sooner too.
zestyping 7y ago
I once read some useful advice to think of documentation in four categories: For work: 1. Playbook (how to do this thing) 2. Reference (what or where is this thing) For learning: 3. Tutorial (practical familiarity) 4. Explanation (deep understanding) I agree that a lot of projects would benefit from more effort in category 4. It might be the most difficult of all to write, though.
- mjw1007 7y ago
  It might. On the other hand, I think if the authors of software concentrated on 2 and 4, they could hope for third parties to help with 1 and 3. Doing things the other way round seems much more difficult.

api 7y ago

The emphasis on getting things done vs. understanding is another manifestation of our age's extreme time poverty. People don't have time to understand anything. Add to that the fact that computing is so trendy. Take the time to learn something -- web development, mobile development, the latest trendy language -- and it won't be hip anymore in 5-10 years. As an experienced programmer I only take the time to deeply understand things that my intuition tells me will be around for a while and for which understanding is a major benefit to me. My intuition is guided by a mix of market share, speed of change in the target market, and robustness of the thing in question.

EvanAnderson 7y ago
It's another manifestation of the classic "it's expensive to be poor" situation. My personal struggle is with making the call re: understanding vs. getting things done compared with the return on investment. Understanding things is fun, though, and our systems are built upon enough analogy that understanding usually transfers (if only in part) to something else down the road.
- thisisnico 7y ago
  Realistically it depends on how invested I am in the system. If it's something that I'm using all-the-time, it absolutely makes sense for me to have a deeper understanding because that understanding could save me time and give me a better perspective on why certain aspects of the system are the way they are. If it's something I use only as an auxiliary system, I don't invest as much time in understanding the system, only what the system can do for me. A prime example of understanding how to use the system, but not the system itself is e-commerce. There are 17+ year old kids making 100K+ a month with e-commerce, having no programming skills or a deep understanding of the web or computers. They are experts at the tools they use, but honestly are not "computer" people. We've abstracted e-commerce to the point that it's not even necessary to deeply understand the web, with tools that exist now (Shopify etc.)
kqr 7y ago
> things that my intuition tells me will be around for a while and for which understanding is a major benefit to me. My intuition is guided by a mix of market share, speed of change in the target market, and robustness of the thing in question. Don't forget about the Lindy effect! A thing that has been around a long time is likely to stay around, whereas something new is much more likely to fade sooner too.

zestyping 7y ago

I once read some useful advice to think of documentation in four categories: For work: 1. Playbook (how to do this thing) 2. Reference (what or where is this thing) For learning: 3. Tutorial (practical familiarity) 4. Explanation (deep understanding) I agree that a lot of projects would benefit from more effort in category 4. It might be the most difficult of all to write, though.

mjw1007 7y ago
It might. On the other hand, I think if the authors of software concentrated on 2 and 4, they could hope for third parties to help with 1 and 3. Doing things the other way round seems much more difficult.