I thought this was going to be a humblebrag -- and boy, it sure started out that way -- but I was pleasantly surprised by the end.
It made me think about how some tools, libraries, or frameworks seem to prefer to use buzzwords or neologisms to make simple things seem complicated. As though by obfusticating the problem domain, they can make their solution seem that much more magnificent. As though the docs should make you feel stupid.
And the reason they do this is because in our industry, it works. Things often seem impressive to the degree that they seem complicated. People are "advertising" their stuff by making it seem like a special snowflake instead of a simple thing.
Far be it from me to blame people for doing something that works. But there is a bit of an echo chamber, especially in this forum, where developers -- developers, not marketers, not "suits" -- prefer to use buzzwords over plain language, and they would rather you think they did something complicated than something simple or something solid.
That is a natural problem in our industry. It requires far more skills to write simple code to solve complicated problems than to write complicated code to solve such problems. What makes it worse is once your head is fully immersed in the problem space, the line between simple and complicated becomes blurry, and what seems like simple solution at the time may seem overly complicated to someone who has not gone through the same thought process.
Sometimes it just takes many tries to get it right. One should not be afraid to rewrite old code until it is right.
The last three Perl codebases I have worked with were overly complicated when I started and had major sections that only a few people had the domain knowledge to touch. With one of those, I became the domain knowledge expert (financial accounting). But the other two I just haven't had time to do that. For example, I am not a quantitative finance guy and I would have to learn that field (and the other is even more specialized).
But what I have learned to do is be guided by a few principles:
1. I much prefer to work with people smarter than me.
2. I try to be good at the little things everyone else ignores ("is this really the right way to handle exceptions?" "Are these functions really written with testability in mind?").
A big problem of course is that codebases don't just fall from the sky, nice and sleek. They are built up over time and entropy within them slowly grows. What starts out as simple get tweaked and made a little more complicated, then again and again until it is a monster you can hardly touch safely.
Simple, beautiful code is darned hard to write and I haven't yet met anyone who succeeds at that all the time (I know I don't). But one can hope with feedback from outside eyes, and a willingness to watch and rewrite over time, that it may eventually get there.
I agree but I'd also like to add that most of the time the complexity for me using some frameworks, libraries, or tools has nothing to do with code but instead in the prerequisites for using them. The authors of some tools make certain assumptions about your knowledge of the whole ecosystem around the tool or supporting tools. Here's a few examples that have caused me pain:
Some time ago, an upgrade to Foundation framework required NodeJS and Ruby 1.9+, a version not preinstalled on my Mac. OK, at the time I knew nothing about NodeJS and have never used Ruby, how hard could it be? 5-10 minutes max?
- NodeJS installed fine, but I had to use "sudo" to install modules or I'd see errors
- Googled... many people used "nvm". I installed nvm, had some issues, but in the end all worked fine
- Next, Ruby. "rvm" is popular, I'll try that.
- rvm installation failed with a cryptic error message, Googled message...
- I need to install "command line tools" which come with Xcode
- I don't have Xcode and apparently it's several GB, after an hour or more I finished downloading it.
- I had to open Xcode, find some random preferences panel and click some button to install "command line tools"
- rvm installation still did not work, Googled.... many people use Homebrew
- installed Homebrew, ruby 2.x installed (with strange warnings) but showed 2.x in the console
- Foundation tools did not work
- Googled how to uninstall Homebrew, found some random "gist" script some guy made which does scary things on my system
- Tried installing rvm again, and for a reason unknown to me, it was successful!
- Foundation tools still did not work
- Didn't notice, last two line of rvm installation required me to copy/paste two lines into the shell.
Great, now I can use Foundation in my Grails project that has nothing to do with Ruby or NodeJS. This whole process took ~6 hours, half of the time I spent just googling error messages.
More recently, I couldn't figure out how to properly package/bundle my React app into a single minified JS file with browserify. The docs linked to a nice simple template:
The package.json has a few useful commands in the "scripts" section:
"scripts": {
"start": ...
"build": ...
}
"npm start" works fine, so why isn't "npm build" working!?!? I posted on stackoverflow and got no answers. Ten days later I figured it out. Knowing very little about npm I had no idea "npm start" was a shortcut for "npm run-script start" and thus I needed to do "npm run-script build".
> most of the time the complexity for me using some frameworks, libraries, or tools has nothing to do with code but instead in the prerequisites for using them. The authors of some tools make certain assumptions about your knowledge of the whole ecosystem around the tool or supporting tools.
Somehow I feel better knowing there's at least one another person on the planet losing 6 hours at time for `just installing X piece of tech`.
Worst thing I had to figure out was that the node package on raspbian is originally related to some radio thing and I had to symlink node-js to node to make it work.
It just goes to show the utter most importance of good documentation. Good as in `human readable` not `logically correct sentences à la man GIT`.
I also felt better when two days later I met a buddy of mine (who is much smarter than me!) for lunch, and immediately he ranted about how he wasted an entire day getting Foundation's command line tools to work. He repeated nearly word for word the same issues I faced!
I'll chuck my hat in the ring here too... got a new MBA recently and it came with Yosemite which introduced one or two curveballs when setting up for web development.
> now I can use Foundation in my Grails project that has nothing to do with Ruby or NodeJS. This whole process took ~6 hours
You've got 3 frameworks installed, each based on a different programming language, using bits from each, whereas each framework was intended to be a "full-stack" product used standalone. If anything, the real issue is with Grails not supporting Foundation.
I'm not really sure I understand your point. The Foundation command line tools require Ruby and Node as dependencies - it has nothing to do with Grails. Are you suggesting every framework, like Grails, should reimplement Foundation's command line tools? Edit: Also, Ruby is a language - not a framework.
Oh, interesting: I've shared a personal insight and I've got downvoted. Point being the downvoter, by not bothering in discussing why she/he has a different notion on this, just penalized that sharing in this collective.
It's a side effect of inter-department competition, as far as I can tell. IT was insecure in the corporate space for a few decades (despite it being as fundamental to most companies as, say, the finance department) and many people fell into the trap of making it sound harder than it is in order to insure some job security.
The funny thing is, you don't need to make it sound harder than it is by making up confusing buzzwords, it's already pretty hard!. Especially in the enterprise space.
Imagine if the logistics department, or the aforementioned finance department decided to rebrand their standard practices every few years. It would cause ridiculous levels of confusion amongst the older workers, as they'd assume they needed complete retraining in this new thing. In reality, they probably just need, at maximum, a refresher course to bring their skills up to date with the newer procedures.
If you ever find yourself describing your latest project to a non-IT-savvy friend or relative, then you quickly realise that the buzzwords and branding are unnecessary to get the concept across. The resulting description, unfortunately, can be pretty boring. The other purpose of buzzwords is to make stuff sound much more exciting than it really is...
It made me think about how some tools, libraries, or frameworks seem to prefer to use buzzwords or neologisms to make simple things seem complicated. As though by obfusticating the problem domain, they can make their solution seem that much more magnificent. As though the docs should make you feel stupid.
And the reason they do this is because in our industry, it works. Things often seem impressive to the degree that they seem complicated. People are "advertising" their stuff by making it seem like a special snowflake instead of a simple thing.
Far be it from me to blame people for doing something that works. But there is a bit of an echo chamber, especially in this forum, where developers -- developers, not marketers, not "suits" -- prefer to use buzzwords over plain language, and they would rather you think they did something complicated than something simple or something solid.