A software architecture doc (e.g. ARCHITECTURE.md) is a way of stating the overall structure of the code. This makes it easier for new people to ramp up on the code base and trims down the time it takes to find where to make a code change.

Best practices:

• Keep it short, the longer it is the less likely is to stay up-to-date
• Specify the things that are most unlikely to change (again to keep it up-to-date), this also gives a frame of reference like landmarks on a map
• Don’t link directly to code since links go stale
• Make it highly visible so engineers go read it often

Read the HackerNews thread

See also:

• Software architectural patterns, having a cohesive architecture makes it easier to document
• It should be obvious to spot if there is conceptual integrity by reading the architecture document

This is a quote attributed to David Wheeler, an early computer scientist who also invented subroutines among other things. Indirection refers to operating on a higher level of abstraction by implementing indirection such as dynamic dispatch or creating object hierarchies in object oriented programming. However, too many layers of indirection can also cause duplication of lower level code so this popular adage is sometimes suffixed with “except the problem of too many layers off indirection”.

A counter response to the growing sprawl of technologies that argues boring technology (tried and true, more mature) is far more effective than the latest shiny tool that gets popular on HackerNews. Using the right tool for the job is often used to justify some new thing, but quickly dissolves when teams write down exactly the issues with the current stack that are not meeting their needs.

Read the blog post

Writing and sharing it is analogous to walking around naked in public. You open yourself up to judgment of others and everyone can seemingly see every flaw. However, once you are ok with that it can become liberating. For example, this video of Neil Gaiman talking about his journey as a writer and overcoming the feeling of judgment.

Read the article

An administrative services organization (ASO) is an outsourcing provider for HR related administrative work. This is similar to a PEO (professional employer organization), but without co-employment. It is significantly less expensive than a PEO because the ASO does not carry employment-related liability.

In 1930, Italian Futurists led by Filippo Tommaso Marinetti declared that pasta should be replaced with futurists foods and in the meantime, rice. He co-wrote ‘Manifesto of Futurist Cooking’ which stated that pasta was the cause of Italy’s problems and holding the country back from being a technological powerhouse. Benito Mussolini supported the futurist ideas and, if not for Mussolini’s need to court an ally in Hitler during WWII (who hated futurism causing Mussolini to distance himself from Marinetti), they might have succeeded in banning pasta.

Read the article

When organizing the information architecture for a website of applications, there should be no straight line hierarchies. This happens when there is a hierarchy of items, but one of the categories only contains a single item. This is confusing to users and unnecessarily adds another layer for users to traverse.

See also:

• UX (user experience)

This note does not have a description yet.

This note does not have a description yet.

Most CI (continuous integration) tools run inside VMs in the cloud sometimes nested in other VMs. This causes pauses in execution as the VM may be applying different techniques to manage multi-tenency—throttling, pausing execution, and so on. Benchmarking code can have different results compared to running locally on your machine for this reason.

See also:

• iai is a rust library with more accurate results for benchmarking by counting CPU instructions

News is the first pass at writing down the history of our time. It’s also largely a rough-draft, information is imperfect and it takes the benefit of hindsight to see stories from all angles.

This quote was attributed to Philip L. Graham, Publisher of the Washington Post when he said “news is the first rough-draft of history”.

Using demos as a way of focusing on specific functionality and elevating quality. Presenting your work builds in accountability and reviewing demos provides feedback. Over time, this practice calibrates people around a set of product principles and shared context.

See also:

• In Creative Selection, the author describes a hierarchical process of demos to ultimately be presented to Steve Jobs.
• Being a better judge of early work inoculates you from skepticism is a counter argument for this process to help early ideas develop.
• Engineering management could benefit from more focus on demos than finalized work.

This note does not have a description yet.

In a study of companies that implemented a topgrading interview methodology, the mis-hire rate fell from 69.3% to 10.5%.

Topgrading is an interview process that includes interviewing for core skills, scorecards, job history review, and reference checks to deter dishonesty.

The topgrading interview walks through their work history and asks about the candidates successes, mistakes, key decisions, key relationship, their manager’s strengths and weaker points, how their manager would rate them, and why they left the job. Candidates that are willing to discuss their full work history provide much more information to the hiring manager and dishonest candidates are likely to drop out.

Read the paper.

See also:

• Performance management is and measuring mis-hires are an important step in topgrading
• The most effective people care a lot which might be a good area for an interview to dig into
• Startups value generalists early, specialists later

On the ascent to K2 in 1953, Pete Schoening saved the lives of five members of the expedition by stopping the fall using his ice axe to wedge against a bolder along the mountain. The story is sometimes referred to as ‘The Belay’.

The city of Topeka, Kansas estimates 10x in annual tax revenue for every $5k they spend in incentives to relocate high paying remote workers to their city. Small cities can build programs that attract individual remote workers that can have an immediate impact on taxes and boost the local economy.

Source

See also:

• Two-thirds of remote workers want to continue to work remotely which increases the demand for relocation
• List of fully remote startups is growing which increases the supply side of the relocation market
• The ‘untethered class’ was most likely to migrate during the pandemic

A ‘weak man’ argument presents a belief that only a small number of people have in order to defeat it. This is similar to a ‘straw man’, but a straw man presents a belief that no one has in order to defeat it. A ‘weak man’ is a more believable logical fallacy.

The profound effect it has is to re-center the category one is arguing against. For example, when arguing against religion, one might cite the Westboro Baptist Church as an example that proves religion is bad. While the one example may be true, it is an over-simplification that re-centers the category on the weak man argument.

Re-centering can grow into a super weapon if it becomes accepted by everyone over time. Even acknowledging the re-centering in order to argue against it, legitimizes it and serves the weak man purpose. This can cause in-groups en masse to conflict against another group even if both groups agree the weak man argument is true (e.g. the Westboro Baptist Church is bad) because re-centering can profoundly change society.

Read the essay.

See also:

• Weak man are persuasive similar to how projections onto different dimensions aids in understanding. The reality is things are complicated, so simplifying categories for people can be extremely effective.
• When groups get involved to defend against weak man arguments (even if they are true) is an example of in-group favoritism and dynamics.
• Related to belief congruence theory, holding one of these weak man arguments might be an important part of signaling you are part of the in-group and therefore gain better treatment.

Ads don’t work by creating a Pavlovian response through association (emotional inception), they work through changing the cultural landscape around us (cultural imprinting). Ads create the impression that everyone else has made the association between a product and a context. Therefore, we make rational decisions by fitting into how other people may perceive what we buy. This largely explains why common consumer goods (highly visible purchases by others) are more effectively advertised at large scale (like the Super Bowl watched by 100MM people).

This only works for products that other people can see broadly. For example, bed sheets can not be advertised in this way because other people don’t have access to seeing your bed sheets so there is no shared cultural context on which to sway your decisions.

Read the essay.

See also:

• Operant conditioning seems related in that we may have been socially ‘punished’ before by receiving judgment about an item we possessed that didn’t adhere to a shared cultural context.
• How Cellino & Barnes, personal injury law firm, works

When using a virtual physical address like Earth Class Mail for business purposes, you need to fill out USPS Form 1583 and have it notarized which requires two forms of government ID.

See the form

See also:

• Back office

A Gallup poll with data from September indicate that two-thirds of remote workers want to keep working remotely. An article from 2016 estimated the number of knowledge workers in the US to be 30MM people and adding roughly 1MM per year. Since most remote jobs are knowledge work jobs, we can estimate 20MM people in the US want to work remotely permanently.

See also:

• The number of remote native companies are likely to increase as a result
• This will increase the back office administrative burden needed to support remote workers

In software development, a simple framework to keep in mind that clarifies how to write certain code is that libraries provide and applications consume. Libraries should useful and reusable in most contexts, therefore it should play nicely with other code and be more or less agnostic. Applications on the other hand are intended for end users and make different trade offs—the code is written for a user not for other code or contexts.

A simple example to highlight the difference is error handling. A library should encapsulate and provide all errors that can be thrown by code in the library so that it’s easily discoverable and can be handled by downstream callers. Applications on the other hand need to catch errors so they can provide feedback to users or log them appropriately—they consume errors produced by the code in their application.

See also:

• This is easily apparent in Rust error handling libraries: thiserror for libraries and anyhow for applications

The number of companies raising a seed round of funding declined from 2019 to 2020 by 27%. Early-stage funding (Series A,B) was down 11% since 2019. This fits with the global trend of number of new startups declining.

A visualization of sustainability represented by concentric rings (hence the doughnut). At the center are twelve factors necessary to support life that array outward. The first ring closest to the center is the minimum required for society to function, but as it extends outward it reaches the ‘ecological ceiling’ such as climate change, pollution, etc.

The purpose of the model is to use it as a framework for making economic decisions. For example, an economic policy could encourage more oil drilling, but that would cause an overshoot of the energy needs of society causing harmful effects (e.g. greenhouse gases, pollution, and land conversion). Using this framework, one could better make decisions that are grounded in sustainability.

See the visualization

See also:

• Civilization is composed of fast layers and slow layers to absorb shocks which draws a similar conclusion about change.
• People are bad at long-term thinking, this model might help make the long term more immediate
• This is similar to the concept of deep time in that it helps show effects that occur over many years.
• Pareto optimal would be the space between the social foundation and ecological ceiling.

Connecting key lines in a document is important to answer the key question and provide clear reasoning. To do that, structure the document using inductive arguments rather than deductive arguments. That’s because a deductive structure could introduce a large distance (number of paragraphs) between the problem and answer which the reader would be required to hold in their head and build their own connections which can be confusing and difficult to read.

As a rule of thumb, deductive arguments are good choice for structuring supporting sentences of a key line in the same paragraph and inductive arguments are a good choice for structuring key lines across a section or document.

See also:

• The Minto Pyramid Principle
• Ideas to support a key line should be inductive or deductive