Use your imagination — could you describe a product which could make your life easier, but doesn't exist, or has not yet become practical?
This is the third post of the Mayfield + DEV Discussion series. Please feel free to go back and answer previous questions as well.
Top comments (75)
Select text, right click, and get a tl;dr for that text
Google announced something like that for Documents at I/O so you might not be too far off that one
Buildable right? As long as the author input the tl;dr
That would be less helpful. I w ant a tl;dr for random text selection, like privacy policies. Lawyers would stop a company from providing one but I think it could be useful.
they would never do that.
Is copilot capable of this?
+++
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.
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 !
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.
"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.
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?
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?
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.
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?
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.
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?
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.
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?
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.
All very good points - I would like to add to your list of things that the documentation often lacks:
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.
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.
That's why there should be competent QA's and Tester's
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.
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?
A simpler way to native android development which is independent of editor used. With every release, it seems that android tools are more deeply integrated to android ide, which makes developing on my 2014 laptop much harder. Since last two release, I haven't been able to configure android studio to use native gradle and native kotlin compiler. Switching to native gradle instead of inbuild one used to give an amazing performance boost. Hell back in 2014, I was able to use sublime text and shell scripts to work on android app.
Hands down the worst DX is when you have an older Android project and have to make any updates to the app. Just launching Android Studio sends you into a spiral of various plugin updates and obscure error messages. TBF though, it's not much better in XCode.
Yes, This was exactly the point when I began to realize the lock-in. I was hired to update a really old project to more recent version of java, along with performing some cleanup. Opening that project in jetbrains android studio was nearly impossible because of all the popups, So I figured I could perform bit of code refactoring in vs-code, upgrade build runtime from java6 to java8, and then open it in android studio. It was nightmare.
I am learning flutter from an older youtube series where the person had configured vs-code, and it seems this is true for flutter too. Yes, command line tools are still available, but IDE-Independent workflow is reduced.
On the point of bundled tooling, In older version of android studio, when you configure it to use system's gradle and system's compiler instead of what is bundled with IDE, the performance was atleast 5x. It also meant that I could share ansible scripts with other team members to ensure uniform developer environment. There were times when I could just run gradle tests directly from terminal for a quicker feedback. But since last two release of android studio, even though I have configured it to use gradle from system, the build button executes the bundled gradle, running gradle from terminal will modify the project forcing you to rebuild it with IDE. Which means everytime I click the build command, I will spend close to 2 minutes waiting for it to complete on my old laptop.
Some kind of communication tool that would help bridge the gap between product and engineering knowledge. These are deeply human problems without a "simple" solution, but I feel like there could be something that could help make the dialog better.
In this case, there's practices that could help all stakeholders to speak one language. I've found particularly useful the practices from the Software Engineering Institute for designing software architectures, that addresses this problem early by doing workshops where every stakeholder is present (even developers, which are stakeholders too). The main practice recommended for this is the Quality Attribute Workshop (resources.sei.cmu.edu/library/asse...).
Train Google Translate to translate between these two dialects?
I don't know of a truly great developer-focused search engine. It seems like there should be a fully specialized tool at this point given Google somewhat getting worse for developer-focused use cases, and yet I still use Google (or Duckduckgo, etc.)
Try You.com
Flicking through responses so far, I tend to concur with many that more tools is not what I need, nor do I feel any springing to mind as needed. But given I do love FOSS and I contribute to it a little in my spare time as and when I need something that isn't there my main desire in terms of products/tools would be anything at all, that makes the process of creating and submitting PRs (Pull Requests, a fancy git era term for a submitted code contribution or patch) simpler, more discoverable and intuitive and streamlined is a big thing I'd like to see.
This part of a broader wish to see community collaboration improve even more. It has seen unprecedented advances in the last decade, but I think is still one of the areas in need of attention to lower the barriers in a sense.
For example, if all IDEs started to converge on a standard open project definition format and build and publish formats ... that would already be a boon. The biggest issue I see in the world around me, I have seen repeatedly described by like-minded individuals as Forking F-in forking!
That essentially every part of the development cycle is dominated by a disorienting and challenging number of options confronted every step of the way, and if you look at n projects you find a call to learn a handful of different tools every step of the way etc.
And so perhaps the biggest product I would like to see existing is "more standardisation". It requires flexible standards, but more than that, it requires competing tool sets to start thinking about conformance to one another bit by bit. A pipe dream, I know. But I dream. And I have seen standards emerge. Browsers are a case in point ... the divergence between them has shrunk to inconsequence. It is doable. We need to share the vision broadly, though ;-).
The mantra being: lower entry barriers, leverage familiarity.
For Git and GitHub specifically, tools like git-town and GitHub's gh (the successor to hub) have short commands for creating PR's. I'm not sure anything addresses making PR's more discoverable. Not sure what you mean by more intuitive, though I agree there's a moderate learning curve to using PR's.
I'd really like version control systems to have a way to annotate a line of code in a way that the annotation doesn't actually show up in the code base proper, but can be accessed through your text editor's integration with the version control.
Things like TODO annotations, long-winded and potentially distracting comments and so on could then be taken out of the code base proper and stored as annotations.
Sort of in this vein is the "Code comments" plugin for Jetbrains IDE's: "[Code comments plugin lets you] Add comments to code of project without change (sic) it."
Non-fragile visual regression testing for CI.
I’m working on it right now: a browser-based tool that will let you define React pages, the actions on the page and links to other pages; then add a template to the definitions for a rough prototype; then run an NPM action to generate a scaffold for the app, with an outer template, routes file and component files for all the pages. I might make an article about it once it’s done 😀
A way to devlop native mobile apps (Android and iOs ) in Rust language.
Better code comments
An IDE integration that prompts you to describe what a method/class/field does, then prompts you to update it whenever you commit a change to that code. Comments are stored in the cloud, not the code repo, and accessible from a web interface (with version history). For open source code, the web interface should be part of the documentation.
Finer-grained version control history
Right click a line of code. Choose "See line history." See a one-page list of every time that line of code has changed, with a commit hash and link for the responsible commit and any relevant PRs.
Big red lever
I want a (physical) big red lever that I can configure with autohotkey or a similar tool so that every time I pull it, it runs
git push. Would this make my life easier? No. But would it make me unreasonably happy? Yes.It looks like two separate plugins for Jetbrains IDE's sort of cover the gist of your comments wishlist (I haven't tried these, I'm just reporting what their blurbs say): "The Better Comments plugin will help you create more human-friendly comments in your code.…" and "[Code comments plugin lets you] Add comments to code of project without change (sic) it."
RubyMine, and presumably all the Jetbrains IDE's, can show version control history for the selected lines (I haven't tried, and doubt would work, selecting a substring of a single line and asking for its history). That view gives a Git commit hash (I don't know what it does for other VCS's, as I don't use them). Linking to the commit and PR's isn't built in. Maybe somebody wrote a plugin for that.
Syntactic translators:
All that shouldn't be something the language dictates but just your personal flavor. I'd like to opt between these possibilities (and probably many more, append below).
I experimented with ANTLR to insert the missing
endstatements when parsing Python and outputting Ruby equivalent. I guess what you would want is to be able to easily plug a parser for one language into a central engine that would have an output plugin for the target language -- the central engine storing the AST or something like that. It wouldn't necessarily be possible for all pairs of languages, but you did say "syntactic", so I think I can omit imperative-to-functional language translation. And then the next step is to make the plugins more granular, so that you wouldn't have to say "input is PHP, output is Bash" but "translate arrow attribute access operator to native accessor syntax of target language-feature-set".Lisps with reader macro capability allow you to define your own syntax additions, but that is an advanced skill, and the syntax probably can't stray too far from the original -- you're never going to get rid of those Insignificant Silly Parentheses with just reader macros.
markdown to twitter as s service
Maybe i have not found it yet. A documentation toolchain like asciidoctor or sphinx for python, that lets me stick with markdown as a base. I'm fine with additional syntax (maybe hidden in HTML Comments?). But i would love to keep markdown. Reason for this that some of my colleagues can be quite resistant to change and would block asciidoc or restructured files.
A simple proxy between different dev servers for web apps for this:
Result: can't set cookies via CORS due too SameSite="None" only with Secure="True"
Yes, I can spin up docker and use some simple Nginx-Proxy. But can't we have this two-in-one-out http adapter as some simple software please? Please make it run like this: