3 ms·
Very controversial topic to wade into, but: I do think that our field suffers from poor explanation of technical topics. I heard this described at a place I use
by randomsearch 8y ago
Very controversial topic to wade into, but: I do think that our field suffers from poor explanation of technical topics. I heard this described at a place I used to work as a "macho culture" - where it was deliberate behaviour as display of aggression, rather than sheer incompetence. Arguably this does relate to traits that men exhibit more than women (on average).
- fullstackchris 8y agoI think it is also out of laziness or simply forgetting to step out of one's own shoes sometimes. It's sometimes hard to explain all the technical parts of a project well to a newcomer who has 0 experience with a particular project when its something you've been working on for months at an in-depth level. We're all guilty of skipping small parts of explanation simply because subconsciously we've done it so much, or it is such a 'trivial' component of a given process or system. These poor explanation and documentation patterns I find most often in open source (though it does indeed occur in industry software as well). A huge number of GitHub READMEs reflect this notion (even in npm packages, for example, that are downloaded 1000+ a week!). To the author of software, the README may be perfectly clear, but for first time users of the software, it can be totally lacking and/or just plain confusing. I always try to be explicit as possible in my instructions and documentation in hopes to battle the field's poor explanation reputation. It's definitely a skill I always try to work on and get better at.