Skip to content

the deep end

A quote from this course.

Please know that our intent here is not to throw you into the deep end.

Rather, being confronted with large amounts of new information is a typical part of life as a software developer.

It may seem overwhelming, but it's important to get experience with leaning into the unfamiliar.

Every new project or development team you join is likely to have unfamiliar tooling and practices that you have to learn to use right away, without immediately understanding every part.

The trick is in breaking down unknowns into basic questions, and learning how to parse documentation efficiently to answer one question at a time.

deep nonsense

We go in circles From 0 to many then back to 0 or 1.

In zen they say the mind is not one and not two, the two are one but one is not two or one or something circular and confusing like this lol.

Rosetta code is a website people upload redundant code to, performing the same task in a wide variety of languages, like listing files in a directory...

Take that one linux command, ls - list directory contents hundreds of languages rewrote a new command to do the same thing using different combinations of words and punctuation.

How many ways do we need to rewrite the command ls? nobody is updating the ls command either, why not update it instead of writing more and more translations of it on top?

If you ask someone they might say - oh it would be better to make the command list-directory or list_dir or lsdir etc.

Verbose is more readable, but people have a tendancy to abbreviate things.

Our minds can pick anything apart for infinity I'm not trying to be fatuous.

This sort of happened at google, not for the sake of cleaning up garbage, but to make the browser faster. The browser reads javascript from a page, now if it's slow javascript they just dump you off the radar, but it used to translate bad slow javascript to a fast version of it, and there were all sorts of duplicated code doing things badly. People created linters and text editor plugins just to tell people when they write code badly lol.

Back to Rosetta code, I think eventually people might build an app to translate the same code from many languages to one. One universal language.

the trick

The trick is in breaking down unknowns into basic questions, and learning how to parse documentation efficiently to answer one question at a time.

Gateway computers (alienware before alienware) had the best training and documentation, those are one and the same. They literally had teams for training and documentation, and people were onboarded quickly and consistently.

Next was Gitlab, they focus on documentation first, "the handbook" but they're still using "copy this command into your terminal" (it runs for me... hope it runs for you) and for me there's still a few key features that don't work without tinkering around outside the documentaiton or "googling it" hoping someone else tried this, failed, and uploaded their notes.

Xerox had decent documentaiton but it not updated and became wonky, based on clunky desktop bloatware and blackberry phone apps...

Documentaiton will evolve, it requires tests, if you type a command into a markdown code block, you might as well also have a docker image run that code in a pipeline that keeps broken commands and configs out of documentation.

Vim is the real key here. Markdown is another one, because there's tools to convert markdown to anything including front ends.

Also I have python click command line interfaces to run apps like awk, grep, pandoc and libraries to funnel bad proprietary formats into markdown.

Jupyter notebooks are also useful for this.

Documentaiton is often an afterthought, and people don't write it out of fear for their job, or being overworked, and when they do they write what they need, what they might forget, not what a noob needs to step in and successfully follow their trail.

I try to document everything I do in hopes that someone else will replace me and I get promoted, and if that doesn't work then I know I'm not at the right company, life is too short for games.