DEV Community

Discussion on: What developer products/tools should exist, but don't?

Collapse
 
chasm profile image
Charles F. Munat

All the below are essentially nonsense. We don't need more tools. What we need is well-written code and complete, well-written documentation.

No one wants to write documentation. I get it. And devs can't write documentation to save their lives. But without decent documentation, the efficiency of dev work is immensely degraded. I have often spent hours or even days trying to track down an answer that could have been rendered in one sentence in the documentation.

And don't even get me started on tutorials that somehow leave out a key step, thus frustrating the reader and proving futile. Or code examples that don't provide the import statements or tell you which file they belong in. What? I'm supposed to write this code on my forehead with a felt pen? Seriously. Tell me where the damn code goes and where you got those imports!

Often documentation looks great and even complete. Until you get into it and it turns out to be gibberish. Documentation is written by people who already understand the code (one hopes), but they need to understand that the reader DOES NOT. Doh! That's why they are reading the documentation! So ASSUME NOTHING.

And FFS can we please have working and realistic examples? Please? Documentation lacking in fully detailed, real-world examples is effectively just a waste of time and resources—yours and mine.

Finally, DO YOU EVEN TEST YOUR DOCUMENTATION? Would you deploy your application without at least some manual testing? No? Then why the hell do you deploy your half-assed "documentation" without testing it on a wide range of beginners to see if it makes sense to them? Oh, too hard? Then you're not serious about gaining market share.

OSS devs often remind me that they're not getting paid. So what? You are advertising your software as a solution. That's a promise you're making to your users. And guess what! THERE IS NO SUCH THING AS FREE SOFTWARE. It does not exist.

All software requires a very significant investment of time, energy, and MONEY on the part of the users. Everyone knows this, so stop lying about "free" software. So how utterly disrespectful is it to your users—the ones you promised to help solve their problems with your "free" software—when you waste literally 20-50% (or more!) of their time because you can't be arsed to write decent and complete documentation.

If you don't have time to document properly, that's just fine. But say so up front! Don't advertise yourself as a "solution" (and especially not as "free") if you aren't either.

When we eliminate poorly or undocumented code (and OSS is not the only perpetrator); feature bloat; poorly written, untested, or insecure code; and absurd claims, then maybe we can start thinking about "cool" tools.

Collapse
 
tomkraus87 profile image
Tom-Kraus87

That's why there should be competent QA's and Tester's

Collapse
 
chasm profile image
Charles F. Munat

What I'd like to know is why OSS is full of devs, but I rarely see any technical writers, designers, etc. devoting their free time to projects. We could sure use some great technical writers.

Thread Thread
 
hotfusionman profile image
Al Chou

I believe that to programmers, programming can be like play, or yields the joy of building/accomplishing. I don't know that the other fields related to programming experience this phenomenon, with the software as the principal product, e.g., I was once professional software QA, and I never had a desire to do any testing outside of my job; and are there many people in the world who love to write descriptions and instructions of things?

Collapse
 
wuarmin profile image
Armin • Edited

OSS is great. That there's not all documented fully every time is a part of OSS. The software evolves and the documentation is often secondary. That's life and we are humans and no machines. Without OSS software development would be hard. Furthermore people get better devs when they look into the code and check what's going on by themselves. After that they are often able to contribute to the code. That's a win win.

Collapse
 
dougatgrafbase profile image
Doug Schwartz

This subject is near and dear to my heart as I have written developer docs for decades. Unfortunately, writers are often brought on board after the project has been underway for months or even years in some cases. It makes it extremely hard to get up to speed and contribute meaningfully.

It's also a challenge when the development team forgets to notify you that they've changed something. It's straightforward to add unit tests to API code examples, but keeping track of UI changes (name is now title) is nigh impossible for any relatively complex product.

You do what you can. I would strongly recommend any docs have a feedback link at the bottom of the page. Just recently I commented on an SDK I used to work on at AWS as their GitHub repo was still referring to the V1 version of the docs, instead of the current version.

Collapse
 
gadgetsteve profile image
Steve (Gadget) Barnes

All very good points - I would like to add to your list of things that the documentation often lacks:

  1. Well structured - i.e. 1. What is it for, 2. Installation, 3. Getting Started...
  2. Readable
  3. Not requiring you to already know the answer to be able to find the answer - a certain well known company springs to mind - if you know exactly what a method is called and exactly which class it is defined in then you can find out all that you need to know.

I do know that a lot of developers find documentation either a chore or outside of their skill set - this is where collaboration can come in.

Collapse
 
lepinekong profile image
lepinekong

It is true I've lost a bunch of time with incomplete tutorials or documentation so I'm for executable documentation concept I'm implemented one form myself see my first comment.

Collapse
 
thumbone profile image
Bernd Wechner • Edited

"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.

Collapse
 
chasm profile image
Charles F. Munat

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?

Collapse
 
hotfusionman profile image
Al Chou

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."

Thread Thread
 
lepinekong profile image
lepinekong

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).

Thread Thread
 
thumbone profile image
Bernd Wechner

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?

Collapse
 
phlash profile image
Phil Ashby

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!

Collapse
 
ben profile image
Ben Halpern

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.

standards

Thread Thread
 
lepinekong profile image
lepinekong

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 ;)

Collapse
 
hotfusionman profile image
Al Chou
Collapse
 
jasonlotito profile image
Jason Lotito

So, rather than provide solutions to this problem, you decided to rant. And in this rant about correctness, you make numerous mistakes yourself.

Otherwise, this is just a rant that is basically "poorly written documentation."

Also, "THERE IS NO SUCH THING AS FREE SOFTWARE"? There is. You confuse free as in speech with free as in beer.

Your comment here is objectively wrong. In a comment harping on the correctness of documentation, I'd hope that you'd work to correct yourself.

And, as for "advertising," this software generally comes with a license that clearly spells out what they are providing. Just because you feel entitled to a certain level of quality above what is promised is your problem, not the provider of the free software.

Furthermore, you ignore the language barrier. Just because documentation comes in English (which is a blessing for native English speakers) doesn't mean it's the writer's native tongue.

That all being said, again, please provide examples of documentation you've contributed to free software so we can see what you considered to be good, high-quality documentation.

A lot of entitlement for someone not putting any effort into improving the situation.

Collapse
 
chasm profile image
Charles F. Munat

This seems like an awful lot of effort to tar me as a bigot while painting yourself as an enlightened being, but all your claims are either straw men or attacking the messenger.

Whether I'm a hypocrite or not has no bearing on my comments. They stand or fall on their own merits. Your attempt to be clever and "flip the script" merely reveals the poverty of your own "arguments". I never said anything about non-native English speakers, for example, so what's that about?

And I have to laugh at your knee-jerk repetition of the old "free speech/free beer" argument. I've been around long enough to remember when that argument was first made by Stallman. But when the developers of most open-source apps say "free", they mean free as in free beer.

Yes, their software is also free as in free speech, but what they are telling their users is that it will cost them nothing to use the software. This is an insidious lie, and the OSS community has gone to great lengths to play down the total cost of ownership, for obvious reasons. But read the history and you will see that internally there has been acknowledgement and continual discussion of the problem of usability and hidden costs.

What surprises me is how many devs are cheerleaders for the status quo and bad documentation, despite that the lack of good documentation is very harmful to the OSS effort. Are you secretly a paid shill for big tech? Why else would you aggressively defend crappy documentation and insist that nothing needs to change?

Thread Thread
 
drhyde profile image
David Cantrell

In my 20+ years of work as a developer of both proprietary and open software, I have not once met a single developer who is a cheerleader for bad documentation. They may not write good documentation - or indeed any documentation - but they've all been aware of the value of good documentation, and would be delighted to accept contributions of documentation for their projects.

I don't believe that you have ever met one of those people either.

Thread Thread
 
chasm profile image
Charles F. Munat

What is the relevance of your comment? Did I say that devs are cheerleaders for bad documentation? I'm not seeing it in my comment.

I'm pretty sure that what I said is that a lot of OSS devs spend a significant amount of time and effort trying to convince people to use their "free" and wonderful software, but can't be arsed to check that their documentation makes that anything other than an exercise in futility. "Free" my ass.

I have personally lost thousands of hours struggling to make various OSS packages work when one or two lines of text in the documentation could have saved me the trouble. The disrespect is astonishing.

Anyone and everyone who uses OSS software regularly knows what I'm talking about. Not sure what planet you hail from.

So what exactly is your point?

Thread Thread
 
drhyde profile image
David Cantrell

Was it not you who said "What surprises me is how many devs are cheerleaders for the status quo and bad documentation" then? Seems like you need to change your password because someone else logged in and posted that foolishness as you.

Thread Thread
 
chasm profile image
Charles F. Munat

Well, you got me there. That said, I did not mean it the way you interpreted it, but I can see how you did.

Put more carefully, a lot of devs are eager to defend the status quo and overlook bad documentation. In that respect, they are definitely cheerleaders for the status quo, and effectively for bad documentation, although they almost certainly don't see it that way.

Maybe a little less literal in your interpretations? I note, too, that you do not acknowledge or bemoan the pathetic state of most OSS documentation, but merely attack the messenger. Should I read that as you like or at least don't mind bad documentation?