30+ years of tech, retired from an identity intelligence company, now part-time with an insurance broker.
Dev community mod - mostly light gardening & weeding out spam :)
Something tells me this is an area you are passionate about 😄
In large part I agree with you however I would like to make a couple of points that occurred to me while reading:
The best documentation I have been part of creating was when working with a Technical Author, who began as a newbie to the codebase, and asked all the right questions, documenting the answers and validating them to create the consumer-facing docs.
Badly documented software should be subject to competition from better documented solutions, and lose market share, or acquire better documentation to compete. Unfortunately this is a time-consuming and inefficient process for all parties - are there alternatives to a messy, painful market though?
In my experience, the majority of OSS is created to solve the authors problem not someone else's, but it happens to be useful elsewhere.. there is little/no incentive to document well as the author knows their own code (until 6 months have passed!) and there is no market/competition. The best documented OSS I have seen is driven by engineering pride, or it is created for a marketplace by a commercial org.
Also in my experience, very little software is created with large budgets and sufficient resources (time & humans) to 'properly engineer' things, especially documentation, then to verify this with consumer groups etc. There are exceptions, in medical and aviation for example, where the risks are sufficiently high, the rest of it is created to earn a return as fast as possible, potentially while destroying the creators reputation as they only care about getting the money out and have no intention of repeating the process - web3 grifters everywhere :(
Perhaps what's missing is acknowledging the cost in time and moral to consumers of badly documented (or badly behaved) software and having a professional reputation to uphold as an engineering discipline? As a technology area, software engineering has adopted a number of 'protected' terms from other fields (eg: architect), but not the ethos behind them. I suspect I am climbing on my soap box here!
I've been thinking a lot about this problem myself lately.
Of course, my imagined solution is yet another piece of software. And I can't entirely articulate it, but come back some time in the future to see if I ever do anything with this idea. 😅
In aviation they use visual programming and generate c code so that's what I'm doing too but pragmatically I also allow 2 ways see prototype in my first comment , demo is html+css but it is meant to be completely language and framework agnostic ie skeleton is separated from the meat ;)
Something tells me this is an area you are passionate about 😄
In large part I agree with you however I would like to make a couple of points that occurred to me while reading:
Perhaps what's missing is acknowledging the cost in time and moral to consumers of badly documented (or badly behaved) software and having a professional reputation to uphold as an engineering discipline? As a technology area, software engineering has adopted a number of 'protected' terms from other fields (eg: architect), but not the ethos behind them. I suspect I am climbing on my soap box here!
I've been thinking a lot about this problem myself lately.
Of course, my imagined solution is yet another piece of software. And I can't entirely articulate it, but come back some time in the future to see if I ever do anything with this idea. 😅
Carry on.
In aviation they use visual programming and generate c code so that's what I'm doing too but pragmatically I also allow 2 ways see prototype in my first comment , demo is html+css but it is meant to be completely language and framework agnostic ie skeleton is separated from the meat ;)
Reminds me of youtube.com/watch?v=Y9ttBt-4vWo !