I also think that anything js-adjacent has a real culture problem. Trying to dredge an answer out of a Medium tutorial written in a cloying tone and interspersed with pointless gifs can be such a groan enducing experience. I'm hoping that the community will mature alongside its technology.
Manpages and documentation are written to be references. Blog posts are written to be tutorials. They have different affordances, and as a result it is very hard to learn how to use something purely from a reference, and very different to solve a problem purely from a tutorial.
That’s why really decent reference sites have both step by-step tutorials AND references designed to answer questions quickly and to be easily searchable.
If there is an opportunity here, it is for search to understand the difference and know how to present the two kinds of results differently.
That way, if you question is, “How does this thing work?” You should get tutorials. If your question is much more specific, like “what parameters does this take?” You should get a reference.
Or something hand-wave-y along those lines.
For example, the other day someone asked on stackoverflow why a particular Java class to calculate a difference between two dates was returning a weird result when they asked for the difference in days. Turns out, the class would calculate the difference in years AND months AND days, so if you asked for the difference between June 23 2018 and June 23 2019, the getDays method would return 0.
While this is something you would find in a tutorial on how to calculate a difference between dates in Java, it's much more expedited to just go and read the reference. Works wonders when you get inconsistent results in C for example, since you're probably invoking undefined behavior which is documented in the standard (i.e., the reference).
As a sort of counterpoint for this particular case, the documentation for that class didn't make how the class was meant to be used clear at all. But in the general case I think it applies.
Either these are very rare, or there are hard to google because they are drowned out by the many tutorials.
When you follow a tutorial, you are shown a very specific way of doing things (which often isn't up to date, with no indication that in the meantime this way has been replaced by another way).
And while that's very helpful for a beginner, it isn't as helpful for an experienced programmer, especially if he or she is having a problem that needs a slightly different way of doing things, and the missing information is just "instead of X, you can also do Y here".
And references don't answer these questions, unless you work through them from top to bottom (which usually takes more time than you have).
Tone is a different matter, tutorials sure can be more lighthearted. But I'd still take a dry tutorial instead of forced, stillborn humor any day. (I'm not sure if the latter kind is all that common in the wild, could be an illusion of frequency on my part).
Tag documents into categories (using ML diceroll, up to one category per document), with a strong bias towards "none" when in doubt. When a search term's results include some categories more frequently than the global average, offer them as filters.
Would its utility survive the resulting wave of SEO innovations?
I don't really get this response. First there's the notion that "webdev" is the discipline where information is so fractured that you need to go googling around to figure out how to do everything. All the other disciplines have a magic thing called a man page that just gives you the answers. This is obviously not true, right?
The second thing is the idea that a man page for any one component, or even a set of components, could possibly contain enough information to allow you to build a complex system without consulting the experience of peers, colleagues and past practitioners, which is at least what we intend to do when we search google.
It is true to some extent. The less dependencies you have the less you need Google. Have thousands of dependencies in node? You will likely google their different error messages a lot. Write low level C libraries where not having dependencies is a key feature? Then Google wont help you much at all, the few times I try I almost never find anything useful for my work.
So the thing about web dev is that you automatically have all browsers as dependencies, not to mention all the libraries, frameworks and api's people are using in modern webdev workflows. Most other fields tend to have much simpler dependencies than that.
Piping six man pages through grep to find what I’m looking for is simply not as fast as Googling an error message.
I think there’s also a sort of cultural difference between languages and tools frequented by newer and older programmers: more experienced people look for documentation and then get working on their project, whereas less experienced programmers look for tutorials and very specific “soft” documentation.
Transitioning from modifying tutorials (the type-in-the-code-in-the-magazine of the 21st century) to glancing at the documentation is probably the surest sign of maturity. Still, you can get a ton done by copypasta.
This might have to do with learning to code with or without the Internet, I’m not sure. I’m personally very envious of people who can take a look at the docs and just get chopping without the assistance of the GIF-covered Medium posts.
This says more about the man pages for grub2 (and grub2 itself, to be honest) EDIT: than about manpages /EDIT.
Compare them with the man pages for grub1. There's a sea of difference.
If you really want to be blown away by a manpage, look for the one for mplayer, which is difficult to find information in for different reasons, i.e., lots of options and lots of options and flags that depend on other flags and options.
In the BSDs, self-contained, complete, and correct documentation is a cultural value. Not one that’s always achieved, but a value nonetheless. Information missing from the man pages is a reportable bug.
And if the man page doesn’t document something, its code is right there in /usr/src for you to dig into.
>Options to GNU tar can be given in three different styles. In traditional style, the first argument is a cluster of option letters and all subsequent arguments supply arguments to those options that require them. The arguments are read in the same order as the option letters. Any command line words that remain after all options has been processed are treated as non-optional arguments: file or archive member names. For example, the c option requires creating the archive, the v option requests the verbose operation, and the f option takes an argument that sets the name of the archive to operate upon. The following command, written in the traditional style, instructs tar to store all files from the directory /etc into the archive file etc.tar verbosely listing the files being archived:
Scanning through the manpage a fair way down and I can't see the one bit info that covers almost all of my use cases for tar.
And for anything more complex than a tiny cli tool the manpage is far too large to use usefully.
but what evs. sometimes the man page is the thing, sometimes not.
There's also a web interface, for tar that'd be: https://tldr.ostera.io/tar
Anyone could divine some reasons for why javascript / “web dev” is so different but I’m seeing shades of the same thing mixed with personal biases towards trade offs and design decisions.
Recently I've been developing in Flutter/Dart, and it's so enjoyable. The Dart language is an improvement on Java, the Flutter documentation and online support is great, apps look and behave the same on different devices, the API and underlying code is well designed. Plus the tooling and IDE integration is first-class.
Perhaps this is because it is just so much less of a hassle to do so in a world with things like NPM.
You don't have to search the internet for web dev any more than you have to do so for any other dev job.
Google: just type in a quick description of your issue and get a stackoverflow post with an answer as the first result.
I don't get how anyone could prefer the man page.
If a library vendor provides good docs on their website, that’s just as good as man pages, but in my experience they usually don’t.
There is a staggering amount of misinformation or non-existent information on Stack Overflow. For one simple example: try to figure out how to use the GPS on iPhone. It’s simply impossible. 99% of people on SO think “GPS” is synonymous with “Location APIs” in general. Of the 1% of people who understand the several different data sources used by CoreLocation, nobody can tell you which accuracy settings will cause it to use GPS specifically. If you bother asking, you’ll get a bunch of “middle-brow dismissals” asking why you want to know such a thing, telling you to just use whatever accuracy setting you semantically need, smugly claiming you’re guilty of posing an A-B question, and so on. This is the type of dead simple basic information I would have expected to be present in Apple’s documentation, instead of having to crowdsource it from internet trolls.
I think manpages are a popular thing to worship here for nerd points but people don't use them nearly as much as they say they do because nobody actually wants to read a manual when they are trying to Get Things Done. Also, some things are just incredibly hard to figure out, like ffmpeg arguments.
Check out http://bropages.org/
Btw if you find the MDN search unsatisfactory (as I do) try mdn.io/search term. It's just a proxy for site:developer.mozilla.org search term + I'm Feeling Lucky.
The problem with a reference is that a lot of times browsers do quirky things and things that are essentially browser-specific bugs aren’t documented in a reference.
Which technology? Web development frameworks seem to have a half-life of about 12 months. 'Mature' and 'obsolete' are near synonymous.
Initial realeases of the most popular JS-frameworks:
Angular – 2010
React – 2013
Vue – 2014
Honestly, a lot of javascript criticism I see nowadays is a little outdated.
All that and emojii's sprinkled everywhere like cat vomit.
and I hate videos cause usually skimming through text you can get to the part you want to read quickly but with videos you need to go through it
It feels like half my job is googling how to do common things in popular libraries and finding completely counter-intuitive pain-points.
I get that these ecosystems evolve over time but I'm not convinced that that evolution requires inability to use the underlying features effectively.
We're building some new infrastructure for a service that is also new, using terraform. Which only our devops have used before.
It's an interesting time.
AWS Cognito with app clients and not user pools + AWS API gateway, connecting to a system linked with dynamodb, Kinesis data stream and firehose.
Like each part stand alone is documented okay with specific circumstances. But nothing interlinking at anything past the basic level.
Trial and error is brutal.
It's like you need to keep an index of things in your head when reading AWS docs as you know the information is dispersed across multiple different places.
Sometimes I wonder if people do it to fill some sort of social need, and don't particularly care for the answer.
Facebook now has enough reach that it includes many people who don't know how to use technology properly. Finding an answer through Google takes a little bit of skill to frame the question and pick the result that will give you the answer.
Roughly 70% of adult Americans use Facebook [1]. This study [2] is from 2015, but it says that only a third of America adults are capable of medium-difficulty technical tasks, such as tasks where you need to '[evaluate] the relevance of a set of items to discard distractors'.
Remember, 20% of American adults have below basic or no literacy skills [3], which means they are not capable of tasks such as:
- "using a television guide to find out what programs are on at a specific time"
- "comparing the ticket prices for two events" [4]
[1] https://www.pewresearch.org/fact-tank/2019/05/16/facts-about...
[2] https://www.nngroup.com/articles/computer-skill-levels/
[3] http://www.ala.org/aboutala/offices/literacy-all-adult-liter...
To be fair, in some cases it's just laziness.
Any given community's patience is, unfortunately, subject to the tragedy of the commons.
It is like organizing a library, by dumping all the books into a pile. It increases engagement at the expense of efficiently finding information.
Most information is extremely niche, but Coding is all over the internet.
I have not been able to google some of my (Industry Level) Chemistry questions.
For example, how many code bases have things ripped straight from StackOverflow in their code? Are any of them attributing the author based on CC-sharealike license? Nope.
How many snippets from GPL code has been used because it was found in GitHub?
So asking google is great, but it could very well taint your code. The next question is if this ticking time bomb will explode now or later
"Memory upgrade" means not relying entirely on your own memory and previous knowledge. That doesn't exclude internalizing the language, nor coming up with new solutions. It probably changes a lot depending on what you do, but I've found it imperative to keep up to date with an ever-changing engine, and it would have been malpractice to just rely on memory, and a great waste of my employer's time.
Anytime I learn something new, I create a simple project using that new thing as a way to memorize it better but also be able after few years revisit it and either remind myself about it or improve it.
I've been thinking about this topic a few months ago when considering how I go about finding out information on how various things are implemented in the Linux kernel, as someone that's not a kernel developer:
* option A is that I start by reviewing the literature (most books are quite old, but I might get lucky) to get a general idea about the topic e.g. memory management under memory pressure. Then I search the kernel docs. Then I use any references that I found to e.g. LWN or similar websites. Message groups search. Finally I would do general internet search, SO, etc. In between these steps I might look at sources, although that's hit or miss, depending on the specific topic. At the end of this adventure, I will probably have a vague or middling understanding of what I was looking for.
* option B is that I ask our kernel expert and he tells me what I want to know, because he's continuously read all of the above resources for the past couple of decades.
So not only is the human memory not obsolete, it is daft to think that Google - which is getting amnesia to boot - could "upgrade" it.
Software is not so complicated that you have to Google search everything every time. If you are not internalizing new knowledge, you are performing poorly.
What kind of software do you write? Software is one of the most unnecessary complex things humanity has invented.
I am a good back-end developer, I'm good at Googling things.
The things I tend to be Googling are typically either superficial, like syntax, or specific as in I know exactly what I want, how do I construct it in x language or y framework? It's quite rare that I have a problem and don't know how to approach it and they're the most fun. Sadly, it's also rare to need to look for algorithms. Just avoiding the run-of-the-mill complexity problems using common patterns or data-structures is sufficient. When they're not (e.g. performance or scale constraints), also fun times.
We have close to the summation of human knowledge at our fingertips. Why would we be embarrassed to harness that power?
Doctors google things, captial E Engineers google things, chefs google things, everyone googles things. Yet you don't hear them talking like this to the extent we do.
Like you said it's knowing what to type into Google, knowing how to filter the results, and knowing how to apply the information you that's the hard part.
for getting started guides, it's great, although even there i'd exercise a lot of caution. there's a lot of info from people who are not experience that people just replicate in their code/setup which isn't really a good idea.
for complex issues you never drown in information. and usually when you find something it probably doesn't apply to your setup. that doesn't mean you can't, at least, get some idea or a pointer to the right solution.
however, just googling or stackoverflowing, i'd be wary of implementing any solution without any thought just because someone else solved it before me.
There are tons of getting started guides for everything but beyond that, one will find a wasteland of information most of the time or it is scattered around in different locations. So in this case the engineer is working hard to figure out which pieces of the puzzle belong in which place. Not to mention that nobody knows how the finished puzzle has to look like.
Edit: relevant XKCD - https://xkcd.com/979/ (and the only thing worse than that comic, is finding someone who had the same problem as you and they followed up with a simple "I solved this" with no additional details!)
That said, the search output wouldn't be of any use without being able to relate it to past experience and accepted practices.
This is 80% of my code, but I only spend 20% of my time doing it.
Its that obscure bug that really requires reading.
I find if I am spending lots of time Googling/Stack Overflow, its for the quick lookup of parameters and a real world example.
Frameworks change, idioms change, but the web itself has largely remained stable (it's still HTTP, even if we now sometimes use HTTP/2). The same security concepts apply.
I feel like I can authoratively answer on more subjects than I could 10 years ago.
Maybe this is mostly related to front-end frameworks? We've only really had one big shakeup in the backend and that's that for the past decade or so we've all moved towards preferring async code (yay Python3k).
“He aggressively encourages the use of search engines”
Because every time they would ask me a question I would ask them if they tried to Google it first.
I'm not sure why people think software development (and computers in general) is somehow different. We don't know everything. We basically can't.
What we (and all other professions) have is knowledge on how to apply new information to what we already know.
So yes, you're right. You have to teach the basics, how to put them together and how to add new pieces once you inevitably hit something you don't know.
I think relying on Google, at least in the initial days of development is bad. I rather developers struggle their way through relevant documentation than google.
You name it, it fits. Knowing when and how to ask for help is essential to everything and an important skill for everyone.
My recommended response is "Nope, you're paying me to understand what's happening, look for possibly relevant information about why, understand what results are and are not relevant, and apply what I've looked up."
I wish I was being snarky, but this is literally true
I would bet that most great developers have googled often enough. In their defense googling is a more efficient tool than pouring through manpages all the time that have poor search indexes.
Also, in this developer’s blog, there is no reference to the fact that his code is buggy or less maintainable, or plethora of other reasons that categorically make him a bad developer.
I think it’s ok, to use help from google or stack overflow to do a good job at your task and that doesn’t make you a bad programmer.
Damn SEO BS is killing it.
I literally said "What would google for?" and then proceeded to invite them to show me in a browser. It gave us a good impression of how good they are at finding answers to coding problems.
This leads me to a hypothesis. I would argue a large percentage of software developers are average, the bell curve for extremely brilliant engineers and extremely idiotic engineers must be be low for each end.
So what is considered average work?
I would working on mundane issues which involves a lot of googling. It would also reason that if you are googling a lot you aren’t doing anything that’s breakthrough or exciting since if the rate of your googling is high that would indicate that the problem you are solving is quite common.
There is a large difference between building things with React and learning how React works and trying to create your own.
I’m not sure why the “re-inventing the wheel” I dread the day we stop innovating and resign our career lives to “well someone else solved this problem so it must be the best solution - no need for me to innovate.”
Re-inventing the wheel is out.
Standing on the shoulders of giants is in, just like Isaac Newton did it centuries ago
I've seen friends and family search for errors or 'how do I...', and their searches mostly yield youtube videos and scraper sites. For me its mostly SE, reddit, and product specific forums.
Knowing how to ask the right questions and understanding jargon is often the greatest asset.
When I interview someone I often ask them what they will do if I'm out-of-the-office, no other senior devs are around, and they need to find the answer to continue to be product - what do you do? You would be surprised how many times I hear 'wait for you to return', versus 'I'd fire up duck-duck-go or search stack overflow'.
Of course, I also pride myself on using good tools. My observation of Stack Overflow is that it's an excellent resource if you don't know what you're doing and don't want to learn what you're doing. Unfortunately, that's the only real way to operate some things. The only times I ever really need to use the Internet for such a problem is when it involves some baroque WWW nonsense some idiot caused however many years ago that's still echoing today or it involves some baroque UNIX nonsense some idiot caused however many years ago that's still echoing today.
If you use good languages and good tools, with real standards, (Common Lisp is an example.) you'll find yourself seemingly magically free from all of this stupid and pointless drudgery. Consider giving it a try some time. Imagine not needing to rewrite code constantly because something updated or some external ''API'' changed or other nonsense.
As a closing aside, it's laughable that people are pointing to man pages as examples of good documentation. GNU Info isn't perfect, but it's leagues better than man pages will ever be, if only because it's segmented and hypertextual.
it's true that in the current "move fast break everything" climate developer knowledge expires at an alarming rate and everything needs to be rechecked constantly trough internet sources to fix integration issues between ever changing libraries
it's also true that searching sources without a solid knowledge base derived from theory and practice quickly devolves into cargo-cult programming.
I too sometimes feel like my skill differential often comes only from being very fast at googling stuff, however this is a gross oversimplification on what happens after the specific knowledge piece is acquired: whether the solution is taken to solve the problem at hand or if it results in a change in one own understanding of the problem domain makes all the difference.
Wisdom is knowing which result to use.
In what other technical field can you simply google everything? And is that because other fields are merely more obscure, or because they’re actually harder? Could one be a mathematician or physicist by googling things?
Most occupations are not intellectual in the slightest, nor do they require a high IQ. They do require other talents, though, such as a sense of aesthetics or technical ability, in this case.
Not being intellectually rigorous doesn't mean they don't require careful thought or mastery.
I could absolutely perform any of the individual steps required to design a website, and have done this. But I either rely on somebody else's template or my designs tend to look like shit. Mostly, I think, the sheer patience to tweak CSS, let alone testing it on a dozen browsers and mobile devices, is often beyond me. Or (Christ, be my shield) dealing with end users.
The simple act of repetitively designing many hundreds of websites and then getting feedback from actual people as to how they work with those sites, that is mastery and it does take careful thought. So, yes, they're constantly looking up "recipes" to combine into code.
Speaking as someone who is on the "tool-making" side of the house, that's the point. I want to make tools that other people can use and combine into new things; if I write a compiler, the goal is that someone can use it without having to learn compiler theory.
The simple act of repetitively designing many hundreds of websites and then getting feedback from actual people as to how they work with those sites, that is mastery and it does take careful thought. So, yes, they're constantly looking up "recipes" to combine into code.
If I were at a party I would appreciate my job being described this way, but the reality is that webdev is mostly applied common sense + having a lot of the kind of knowledge that is googlable. Like, I’m successful career wise and I’m regarded as being quite good at my job, yet I don’t feel like I’ve mastered anything per se.
Whereas for my side project, an IDE for Golang, I feel I’ve actually had to learn difficult concepts that couldn’t be re-learned from a blog post.
I take back what I said about webdev not requiring thought, which was an exaggeration.
Knowing how to quickly find what you need is not in conflict with mastery...besides, we are talking about web apps here, most dev teams wont have much patient with a developer spending a ton of time reinventing wheels when there are ready-made solutions.
Not really, the same rule applies for a hell of alot of other things.
>And is that because other fields are merely more obscure, or because they’re actually harder? It's simply because other fields don't have the same knowledge sharing culture and you end up having to use SciHub and doing the knowledge sharing yourself.
>Could one be a mathematician or physicist by googling things?
I think a number of fundamental cultural problems with mathematics needs to be fixed before this is viable for the broader population, but I do think it may become the case over time.
I'm a middleware support engineer. A reasonable amount of experience, coupled with Google, will solve many problems.
That's funny, khaliq means creator in arabic...
Every time a user has to ask a simple question and they have access to the docs, I see it as a 'product fail'.
