4 ms·
It's not just that it "requires maintenance". The maintenance itself is duplicated effort, which is often not done well. So you spend countless hours convertin
by P_I_Staker 3y ago
It's not just that it "requires maintenance". The maintenance itself is duplicated effort, which is often not done well.
So you spend countless hours converting a perfectly acceptable language (code), into "plain english". The result is often so poor, and no better than the code, that nobody uses it (for good reason). Then what's the point of keeping the doc? so you just have these old relics, ancient books that provide no insight whatsoever, but nobody wants to delete.
IME a lot of older engineers are still stuck on this fantasy that we're going to eventually do all engineering "in plain english". Some of these ideas have thankfully died off, but 10-20 years ago, lot of these people were running amok making crazy demands that everything read like a book. Do technical work without doing it, basically.
This is a pipedream that's existed as long as software. Maybe we'll get there someday, but it seems like some things are moving more technical and less "intuitive". For instance, many of the same older engineers seemed to assume we'd stop using the command line.
It seems that most of us have abandoned this, but I've encountered a few that assumed we'd just be passed this by now. I can't completely fault them for this instinct.
- hu3 3y agoIn find that documenting the Why with code comemts helps. Keep it concise. Something like: // We no longer allow deleting users data immediately because we are required by law X in jurisdiction Y. See ticket #3256149