"No one wants to write documentation." - Not true. I want to. And I do. Regularly. There is a resource management issue though and a gotcha, a catch 22 of sorts. That is, I love writing documentation that needs to be written, and that I can write well, which by definition is essentially documenting my own work. But therein lies the resource crunch. Any moment I have in front of a screen working on project X of the many projects on my desk, in my minimal available time, I'm either doing the next bit of dev or documenting the last bit and the choice is as much based on mood, and focus as it is on want and desire. The mid-ground I find is hastily written in-line docs (in the code base). And I have yet to implement any way of converting that on any project to documentation. And that is probably a lower priority that getting solid testing infrastructure prioritised as my project(s) grow etc. These are the consequences of FOSS of hacking and of taking on passion projects and idea because .... I can.
That's the story for the passion play, if you will, the FOSS work I do a few nights a month when the kids are in bed ;-). Did I mention a resourcing issue?
Professionally, it's a bit different. I have been employed as a technical writer at least twice and have hired technical writers and always worked on projects where the documentation was seen as a crucial resource and funded.
I work with pedagogies, teach, write curricula, coach, manage, mentor, consult, speak publicly, polemicize, and sometimes work as a full-stack web developer, architect, ontologist, and more.
Yes, this is the problem. Documentation is hard work, and no one wants to do it. And although the OSS community is good at attracting developers, it is not so good at attracting technical writers, designers, UX engineers, etc., with the consequence that OSS often suffers compared to proprietary software.
This leads me to believe that most devs, despite their regular and vigorous patting of themselves on the back, are not really in it for altrusitic reasons. If that were true, then are we saying that devs are altruistic by nature, but designers, UX researchers, etc. are not? I find that difficult to believe.
So that punctures yet another fable that OSS devs tell themselves: that it's about altruism. In my view, it's mostly about ego, career advancement, and necessity with "altruism" as a convenient cover. And the unwillingness to make an effort to document well just proves my point.
I would love it if OSS were what it pretends to be. But after nearly three decades of struggling with it, I find that it's nothing like the claims made for it. It is still greatly useful, and I certainly wouldn't want to go without it, but why can't we just be honest about what it is, what needs it fills, and why people actually build it?
Have you ever tried Literate Programming en.wikipedia.org/wiki/Literate_pro... ? I like the idea, but then I'm reminded of the joke, "Make it possible for programmers to write programs in plain English, and you will find that [many] programmers cannot write plain English."
Well the implementation is old but the concept is good and I use it in my own visual programming tool. In it I mixed all concepts that I find USEFULL because I'm doing the guinea pig on itself (eating own dog food) with a code base that has reached already 45000 lines of javascript for a figma plugin that is huge (generally an already big plugin is like 2000 lines of code).
I've not tried formally literate programming no. I was inspired by the idea when it first crossed my eyes a few months ago because I (and many others I am sure) invented a similar idea in the 1980s. It was born of entry into the IT sector faced with legacy code (FORTAN IV) written in such an obtuse manner that it was black boxed for many years since no-one game to touch it as they could not understand it and there was no regression testing infrastructure in place either.
I rewrote code like that in the more modern FORTRAN 77 of the time and established a pattern of code files that had more English in them than code. Extensive internal documentation that often had a paragraph describing the raison d'etre of a single line of code.
At the time the Usenet was the thing (pre-web and much of the academic world connected on dial-up links still) and there was a string of jokes in a group call rec.humor.funny that had the proforma: A bad X does A and a good X does B.
In the day the buzz language was C and so I submitted something that ran a bit like: The bad programmer writes code in C and documents it in English, the good programmer writes code in English and documents in C.
It was published in a paper anthology of rec.humor.funny quotes one year too, though I can't recall when but here's a candidate (I might have to try get that and see):
"No one wants to write documentation." - Not true. I want to. And I do. Regularly. There is a resource management issue though and a gotcha, a catch 22 of sorts. That is, I love writing documentation that needs to be written, and that I can write well, which by definition is essentially documenting my own work. But therein lies the resource crunch. Any moment I have in front of a screen working on project X of the many projects on my desk, in my minimal available time, I'm either doing the next bit of dev or documenting the last bit and the choice is as much based on mood, and focus as it is on want and desire. The mid-ground I find is hastily written in-line docs (in the code base). And I have yet to implement any way of converting that on any project to documentation. And that is probably a lower priority that getting solid testing infrastructure prioritised as my project(s) grow etc. These are the consequences of FOSS of hacking and of taking on passion projects and idea because .... I can.
That's the story for the passion play, if you will, the FOSS work I do a few nights a month when the kids are in bed ;-). Did I mention a resourcing issue?
Professionally, it's a bit different. I have been employed as a technical writer at least twice and have hired technical writers and always worked on projects where the documentation was seen as a crucial resource and funded.
Yes, this is the problem. Documentation is hard work, and no one wants to do it. And although the OSS community is good at attracting developers, it is not so good at attracting technical writers, designers, UX engineers, etc., with the consequence that OSS often suffers compared to proprietary software.
This leads me to believe that most devs, despite their regular and vigorous patting of themselves on the back, are not really in it for altrusitic reasons. If that were true, then are we saying that devs are altruistic by nature, but designers, UX researchers, etc. are not? I find that difficult to believe.
So that punctures yet another fable that OSS devs tell themselves: that it's about altruism. In my view, it's mostly about ego, career advancement, and necessity with "altruism" as a convenient cover. And the unwillingness to make an effort to document well just proves my point.
I would love it if OSS were what it pretends to be. But after nearly three decades of struggling with it, I find that it's nothing like the claims made for it. It is still greatly useful, and I certainly wouldn't want to go without it, but why can't we just be honest about what it is, what needs it fills, and why people actually build it?
Have you ever tried Literate Programming en.wikipedia.org/wiki/Literate_pro... ? I like the idea, but then I'm reminded of the joke, "Make it possible for programmers to write programs in plain English, and you will find that [many] programmers cannot write plain English."
Well the implementation is old but the concept is good and I use it in my own visual programming tool. In it I mixed all concepts that I find USEFULL because I'm doing the guinea pig on itself (eating own dog food) with a code base that has reached already 45000 lines of javascript for a figma plugin that is huge (generally an already big plugin is like 2000 lines of code).
I've not tried formally literate programming no. I was inspired by the idea when it first crossed my eyes a few months ago because I (and many others I am sure) invented a similar idea in the 1980s. It was born of entry into the IT sector faced with legacy code (FORTAN IV) written in such an obtuse manner that it was black boxed for many years since no-one game to touch it as they could not understand it and there was no regression testing infrastructure in place either.
I rewrote code like that in the more modern FORTRAN 77 of the time and established a pattern of code files that had more English in them than code. Extensive internal documentation that often had a paragraph describing the raison d'etre of a single line of code.
At the time the Usenet was the thing (pre-web and much of the academic world connected on dial-up links still) and there was a string of jokes in a group call rec.humor.funny that had the proforma: A bad X does A and a good X does B.
In the day the buzz language was C and so I submitted something that ran a bit like: The bad programmer writes code in C and documents it in English, the good programmer writes code in English and documents in C.
It was published in a paper anthology of rec.humor.funny quotes one year too, though I can't recall when but here's a candidate (I might have to try get that and see):
netfunny.com/inetjoke.html
but might have been something else I'm remembering too.
"Well the implementation is old but the concept is good and I use it" - what implementation is that you're referring to?