3 ms·
For hundreds of years we've been writing summative introductions called "abstracts" to long documents called "journal articles", "lede" paragraphs introduce "jo
by mch82 11y ago
For hundreds of years we've been writing summative introductions called "abstracts" to long documents called "journal articles", "lede" paragraphs introduce "journalism", and "introductions" summarize "books". People understand how to use these conventions. How is it easier for the end user to have to learn to install, use, and understand an additional tool chain? How is it easier for a project maintainer to manage documentation in multiple locations?
https://xkcd.com/1319/ https://xkcd.com/1319/
- falsedan 11y agoIt's not easy? It's hard to write documentation that's suited for reference AND expert users AND new users. All of the materials you mentioned are for informing/entertaining people, not training them to acquire new skills. There is a field of study specifically for this: education. Also, be less patronising.
- mch82 11y agoI guess that for me the git man page does it's job as the quick summary for how that program works and git-scm.com/book is the training tool I rely on as a new user. There is so much to learn that a man page cannot concisely cover, like how to structure a collaborative workflow in a distributed team. For that, turning to a well written book has been key. I'm definitely not suggesting that writing useful documentation is easy. I agree with you that it takes work to write documentation and training material that people can use. Not my intent for the prior post to be patronizing. Sorry it came across that way.