How did I run that code again? Tools to help recall

In the physical world or in GUIs if there's a concise bit of large text in front of you it can be hard to ignore. But the command line is a barren wasteland until you take action. This tip basically brings what the author sees as a minimal documentation / GUI to every project via a command that they run by habit now upon project entry.

There's also a good point that documentation is a PITA and so you should try to make a doc generating tool that extracts the most critical info you need to use a given project from the code itself so you don't have to repeat yourself. The author determined that aliases set in the project are such critical info for example.

I think it would be fun to write a 'universal' `help` tool that took some of these heuristics and tried to produce minimal docs from any directory that was discernibly part of a coding project. Delightfully open-ended and unsolvable, probably needs some machine learning sprinkled on top as well.

On my iPhone Firefox screen real estate, nearly 2/3rd were taken over by website’s navigation area (or is that the floating outline index of the article itself?).

Despite that challenge, I doggingly read on with the main portal that mainly and underwhelming overtook 1/4th the screen.

Good article. Hell of a website although.

The main things I have figured out are, 1) use a script to contain all the stuff I know I will not remember, 2) structure projects so that there is a script for each environment I have to work on, 3) be rigorous in making all that structure the same because I know I will not remember where the script is if it's different, 4) use aliases (also, btw, listed in my .bash_profile) to execute them so I am not confused and 5) make sure to write all the fussy details in those scripts and keep them up to date and refactored frequently.

Feedback welcome.

It's maybe a little too weird to be able to practically recommend generally. (It's very difficult to deal with unhappy cases; you really need to know what you're doing to work through those). But, the promise of being able to have a development environment made available with a single command by having declared the programs a package is built with is really neat.

Yep.

What happens is that I spend almost all of my time and energy on third tier priorities and problems because I’m a coder, and if things have clear cause and effect I’m going to automate that shit the first time it pisses me off or embarrasses me or a peer.

The longer I’m on a project the more bimodal is my set of focuses. Really big picture, and niggling little minutiae. God knows what it’s like for someone interviewing me and asking about my last gig.

We have robust documentation and we've practiced engineers maintaining a "stash" repo for their notes, which may sync back up to the primary documentation. We also make an effort wipe our stack and redo it every 2-4 weeks, so that we understand the warts while potentially finding new ones.

We'll slowly move towards better developer experiences (and Makefiles are honestly great for most use cases), but a documentation culture is most important right now.

The last time I did this, I wrote a self documenting bash script project.sh similar to the last Nix example with a list of commands and a help text and menu options.

Another useful object is not just unix history but a tool like Rash in Python, advanced bash shell history stored in SQLite. There are many similar tools nowadays but then you can look for commands you run in this project directory structure in your cli history. Projects are not flat, so there may be specific commands needed in certain directories.

the first target is 'help', so when you enter the directory, you run make and it spits out a list of possible targets.. The help target is just a bunch of #comments.

Each target does some sort of useful thing, like regenerating swagger, cleaning up temporary crap, starting in dev mode, etc.

Coupled with a readme it's the best, simplest approach.