Most programmers believe a number of blatant falsehoods about documentation, with the most prevalent being "comments go out of date quickly, so there's no point in investing in them". Maybe I'm just hyper-aware of it because my short-term memory sucks, but code comments have saved me on so many occasions that they're simply not optional.
You can document your code. You can keep it up to date. It isn't that hard. You just don't want to.
I will have to disagree. New ideas are rarely totally new, and often build on old ideas. Keeping old ideas in your brain will help you come up with new ideas.
One of the big advantages of having stuff in memory is that you can do background processing.
I can't tell you the number of problems I have figured out while going for a long walk, or driving in my car, or even sleeping (all of a sudden I wake up with the solution).
For example, how to get the length of an iterable in a given language. I may not remember the function name (or if it's a top-level function vs a method) but I know I can search "string length in $LANGUAGE" and find it. This scales better than memorizing every language feature I'll ever use.
PS: Dash is a great mac app, highly recommend. Your job will likely cover it if it's something you think you'll use.
Sure! If you just assemble a page with about 500 button or links, and know which one to click on to get the needed information, everything is a click away!
You of course can't use them without permission, but I've found them interesting before.
Old man mode
Remember back when Linux systems just came with huge packages of documentation? You could do anything offline by reading man pages or looking through /usr/doc/, /usr/share/, etc.
“Normally, flies will remember very well and will get an A if they are tested a few minutes after learning. But if there is long time between learning and testing, which for a fruit fly is 1 day, they will forget and get an F”
A fruit fly lives for 40 to 50 days, so 1 day isn’t a long time to remember things for them.
“Flies form a memory of locations they are heading for. This memory is retained for approximately four seconds. This means that if a fly, for instance, deviates from its route for about a second, it can still return to its original direction of travel.”
I couldn’t find how many things they can remember simultaneously.
It's much easier to modify and maintain your own software which is purpose-built to your needs than it is to maintain somebody else's code that was built to their needs, and was probably overcomplicated to make it as a generic library.
For a compiled language, you have the extra complexity of integrating its build system into yours.
So I'd say you should still weigh carefully whether you want to pull an extra dependency or not.
Just taking the time to actually learn what the standard library of the programming language you are using provides can dramatically increase your productivity. The same with important libraries you are using. Yes, it is too much to memorize everything but just knowing what actually is there will help you a lot. You can not search for something you don't know exists.
I also really love working on solo projects because I tend to memorize the general shape of the code I am working on. This makes me so much more productive. I might not remember every single line of code in detail but will have a pretty clear idea of the shape of the program. This means I can plan new features or doing refactors in my head and see if they would work. I don't need to sit in front of the computer. I can do the hard mental work while taking a shower or going for a walk and can type in the code afterwards.
Anyone else work like this?
Currently has plugins for Vim (proof of concept) and Emacs (actually good). It'd be lovely if one of you folks would make a VSCode plugin for it. I've thoroughly documented the API and diagrammed the code flow you'd need, so that this would be as easy as possible to add to your favorite editor.
> While Dash is a $30 Mac app, there’s the free Windows and Linux version called Zeal, and a $20 Windows app called Velocity. Of course there’s also at least one Emacs package doing the same thing: helm-dash.
Quit smoking pot and things got a lot better for a while, but then things seemed to resume their downward slide. Sleep apnea didn't help, and treating it made things better for a while, but that slide continued.
Now I just try to manage it with lots of notes, scripting everything I can, and trying to simplify my workflow wherever possible. Hopefully things stabilize in my 50s or I don't think I'll be good for much engineering work beyond that. I have a number of dopamine-related movement disorders though so there may be some special issues in my case.
Then 2 paragraphs in I run face first into a 5 meter high stainless steel marketing pitch. Wtf.
- the last release was October 2018. The repo shows activity up to 2 months ago, and I'm sure the last release works fine, but it doesn't seem very active.
- the installation documentation is very much lacking. The "make -B build" on the README doesn't work, the build instructions on the wiki is empty except for per distro instructions, the package release for Debian doesn't exist, and the ppa points to an old IP.
That said, I got it working. It seems pretty cool, haven't used it yet, but from what I can see, it is very mouse centric and no keyboard controls, has popup windows and a system tray icon (I loathe them), so for a tiling wm not quite the best. But it does what I need it to do: download docsets, keep them up to date via the RSS feeds for Dash, search them.
I'd love a tool like this but more keyboard oriented, specifically vim like keybinds but any keybind system would work. I know there's an emacs package "helm-dash" but I don't use emacs. I might try it just for this tool.
All in all I think this is going to make my life a lot better. I like to disconnect from the world, but I want to be able to code while disconnected and zeal could enable me to do that.
As soon as I hit 40, I can't remeber what I did last week or before that. Did I solve that problem? Which customer complained about it? Where did I put that PDF?
Fortunately I am very organized, and I leave clues for myself all over the place. Readme files in named folders, details in commits, email myself with some information.
But more than often I am asked "was X display compatible with XYZ board?" and I can't give a direct answer anymore.
Now I want to be honest, I have been trying for a bit over an hour to add ANY documentation that is not included by default. It's way too complicated. Has anyone found any success?
Docs from pyspark, azure data factory, databricks, anything big data related would be a gift for me. But the steps are overtly complicated.
Specifically, in the "Building documentation" part of the article, it's where you are supposed to use doc2dash and use to add new info. If someone or even the author has managed to add any not supported doc, and wants to share, it'd be much appreciated.
Otherwise I am left with the question, how many hours are you supposed to spend in order to save time with each search? Because this programs seem unbalanced for people without the know-how to even start.