Opinion piece: What we can learn about documentation and logging I have a long history of telling people I'm the dumbest person in this industry. This comes with the con that people think I'm dumb, but also an amazing pro. If I can read your documentation and use your tool, you did an amazing job because you got an idiot like me to use it. Extra points for a fast "aha!" moment. and are f*cking shit, I hate javascript, and can someone / something please address the dumpster fire we have going on holding the entire front end of the internet together. It's 2 AM, let's chat boys and girls. NPM yarn Welcome to Hacker f*cking noon, where we can write sh*t like this. you a picture.... Let me paint I need to upload some code to the cloud, what code isn't important. The README.md for step 1 is clear as day: Requirements yarn Run ```make zip adapter=coinpaprika``` Simple, I need yarn, then I need to run that command. Now, I have worked a lot with python, and maybe I'm spoiled because works 99% of the time, but this can't be much worse right? I have a macOs, how do I install on this OS? Let me go to their . It seems so straightforward! This is great! I can run one of multiple commands, let me just try the easiest. make pip install documentation page brew install yarn And I get an error: curl: ( ) The requested URL returned error: Forbidden > Failed to download https: 22 403 //yarnpkg.com/latest.tar.gz. Hmm, not sure what that means, but no worries. I can just google this, maybe the site is down? Maybe I have weird firewall rules? The triage list of possible issues is pretty long here, and I explore a number of them. After unsuccessfully triaging, I decide just to move onto the next command. I don't really need to become an expert on the ins and outs of this package to use it for it's intended purpose right? sudo port install yarn After trying this I get a number of other weird issues, follow similar triage paths. So let me try something else. Let me dig even deeper trying to figure out what I'm doing wrong. I google the error Check github for issues Try the command on my friends computer and ask them Spin up a Ubuntu VM in my Google cloud and try to install using the f*cking Ubuntu commands it f*cking supplied, and then start to google and triage those errors, till finally I come across this sh*t. You can install yarn with NPM, just run: npm install yarn -g I suspect this won't work, but I of course try it both on my mac and my linux VM anyway, and then proceed to lose my f*cking sh*t. The INSTANT I saw npm I knew all hope was lost. Which brings me to my first point. 1. Clear, concise, logging is critical You are a coder, you work with computers. We get it, we are technical people, however the users trying to use your tools are human. When an issue comes up, a human is going to fix it. Not a robot. A human. And humans are emotional creatures. Every second your tool is being debugged by a developer, their hate for your stupid logo grows, and want for an alternative grows. It's a great way to drive away developers. So if you'd like your project that you've spent years building to be despised by the community and moved on from, then please, don't add logging. I know it's hard and a bit tedious, but every time you get an error and someone doesn't understand the issue about why the issue happened, you have a responsibility to upgrade your error and documentation so that anyone can use it seamlessly. Here are some tips. Here is a great example of what I think is sh*t: : [~/code/lottery-react - (master)] $ npm run start patrick@Patricks-MacBook-Pro-2 > lottery-react@ . start /Users/patrick/code/lottery-react > react-scripts start There might be a problem the project dependency tree. It likely a bug Create React App, but something you need fix locally. The react-scripts provided by Create React App requires a dependency: : Don try install it manually: your manager does it automatically. However, a different version babel-eslint was detected higher up the tree: /Users/patrick/code/node_modules/babel-eslint (version: . ) Manually installing incompatible versions known cause hard- -debug issues. you would prefer ignore this check, add SKIP_PREFLIGHT_CHECK= an .env your project. That will permanently disable this message but you might encounter other issues. fix the dependency tree, try following the steps below the exact order: . Delete -lock.json ( .json!) / yarn.lock your project folder. . Delete node_modules your project folder. . Remove from dependencies / devDependencies the .json your project folder. . Run npm install yarn, depending the manager you . most cases, this should be enough fix the problem. this has helped, there are a few other things you can try: . you used npm, install yarn (http://yarnpkg.com/) repeat the above steps it instead. This may help because npm has known issues hoisting which may get resolved future versions. . Check /Users/patrick/code/node_modules/babel-eslint outside your project directory. example, you might have accidentally installed something your home folder. . Try running npm ls babel-eslint your project folder. This will tell you which other (apart from the expected react-scripts) installed babel-eslint. nothing helps, add SKIP_PREFLIGHT_CHECK= an .env your project. That would permanently disable this preflight check you want proceed anyway. P.S. We know this message long but please read the steps above :-) We hope you find them helpful! npm ERR! code ELIFECYCLE npm ERR! errno npm ERR! lottery-react@ . start: `react-scripts start` npm ERR! status npm ERR! npm ERR! Failed at the lottery-react@ . start script. npm ERR! This probably a problem npm. There likely additional logging output above. npm ERR! A complete log this run can be found : npm ERR! /Users/patrick/.npm/_logs/ - - T04_38_46_190Z-debug.log 0.1 0 with is not in to package "babel-eslint" "10.0.3" 't to package of in 6.1 2 is to to If to true to file in To in 1 package not package and or in 2 in 3 "babel-eslint" and or in package file in 4 or on package use In to If not 5 If and with with package in 6 if is For in 7 in package If else true to file in in case to is 1 0.1 0 Exit 1 0.1 0 is not with is of in 2020 05 08 What the f*ck Usually, my terminal doesn't take up the whole screen, so I only see the bottom. I can only image a new developer's reaction seeing the screaming at you 50 times. Giving them flashbacks of father beating down the door in his drunken stupor at 2 AM, just for trying to get to actually print "helloWorld". npm ERR! helloWorld The GOOD thing about this (if you don't instantly go catatonic), is that if your anxiety meds calm you down from the epileptic induced error overload, if you scroll up, it does give you some good tips that DO usually solve the issue. Which is: You probably forgot to run npm install silly Which I have a different issue with, and seem 1000% times simpler... Am I wrong? Please let me know. A rant for another day.... pip install requirements.txt Anyway, the logging has a lot of good information in it, which is awesome, and it is clear, which I love. The part that is ass is the fact that it's the length of an 8th graders essay where the grading rubric was based solely on whether or not they hit 1,000 words. VERY The other issue is why the living hell are such a massive file? Am I just a python brat? And a java brat? And a go brat? Why is it that I don't have this massive folder on any other language. Ug, that's a rant for another day. node_modules 2. Documentation needs to reduce friction If you want people to use your tool quickly and efficiently, they need to have an " " moment quickly and efficiently. This is especially true for new developers, since ofter once someone finds a tool that works, . aha! they tend to stick to it Let's look at the documentation for pip and npm? Each home page has a "Getting started" or "Quickstart" page. Great! That's what I want! To quickstart! : Here is python/pip's In this first section I now know almost everything I need to know. The rest of the page is as concise and beautiful as this portion. If you even hit that link, you reach a page where the first line says: install pip pip is already installed if you are using Python 2 >=2.7.9 or Python 3 >=3.4 YES. THIS. EVERYTHING ABOUT THIS. ITS ALREADY THERE. I'm going to need it! Why would it NOT be installed??? What's the most important thing I need from pip? What is right at the top of the documentation? Brilliant right? It's installing packages. How to install packages. : Now we go to npm's You would think the most important thing is creating a new user account or paying for your account. Ya know, since they put those at the top. But it's not. It's not the most important thing. The most important thing is installing packages. 3. The ridiculous dependencies This is the one most people quote. Since javascript doesn't have a standard library like python, people are free to write there own and import anyone else's. This has the massive pro of being open-sourced as hell, but the massive con of no consensus at all, and sometimes for you to use one package someone wrote, means you need to install 2,000 other random files. Talk about "lightweight". Oops. This can mean that if one package is updated, broken, removed, fixed or something, your code may no longer work, and when you go to debug it you have to go 10 dependencies deep to figure out the actual issue. This is all over the world. exactly what happened in 2016 Not to mention that I just praised npm for being open-sourced as hell, except in this same instance they kicked someone's package to the curb to make room for a bigger companies. #openSourcedUnlessYoureNotABigCompany Photo by on Mohamed Nohassi Unsplash Summary Look, at the end of the day, I was eventually able to work out the kinks and get my project to work. And I know if I spent more time reading through everything I probably would be a lot better at these technologies. I'm not a javascript pro by any context, and I know that a response can be "Well then why do you say they suck if you're not even a pro??". First impressions are huge. And what I'm trying to say, is that the experience of working with these tools, especially early on, shouldn't be this frustrating. If you want developers to work with your tools, reducing the complexity and friction should be a top priority. It feels like npm has reached a point where they are saying: "Well, the web is built on javascript, and we are the dominant package manager, so they will have to come to us. F*ck them." (Not an actual quote) I think this will be a massive misstep for them, as we saw Microsoft go through nearly exactly the same journey. Becoming complacent, started building shit products, and then . becoming dominated by competitors who were sick of their shit I also don't want to say pip is perfect. Virtualenvs are the programming equivalent of "wtf" for beginners, but somehow I (being the dumbest human in the industry) was able to figure it out. And if you don't believe me. Google "npm is bad" and read the shitstorm of posts about how bad npm is. From being a , , , , . poorly managed company more information on the joke of package dependencies why we need to address the issue of npm the million devrants from this site hacknews and reddit filled with hate And now me too. Let me know if you think I'm just a shitty pissant coder, brilliant documentation analyst, or something else. I have more helpful content 99% of the time, like blockchain tutorials, python and machine learning, and fintech engineering. Follow me on , , , and ! Medium Twitter Youtube GitHub
