People programming: An exploration of the similarities between writing instructions for people and for computers

Ideas / Scratch pad


  • Come up with a list of problems and their corresponding solutions that will serve as the basis for your chapters.
  • Use your phone to dictate your intro to the book, where you explain how you got thinking about this stuff.

Chapter list (WIP)

  1. Introduction / overview of the remainder of the book / how I got the idea (?)
    1. As a quick explanation, just show the CFPB's prose in its original unstructured form, and then what it looks like when it's structured.
    2. How I arrived at this idea:
      1. Talk about how I did my senior thesis in philosophy on the poor structure of the texts in philosophy.
      2. Talk about how I studied for the LSAT for a year, and one of the big things I noticed while I was studying was that sentences had certain relationships to each other, so I would label things as 'MI' for 'Main Idea', 'EX' for 'Example', etc.  But the structure of the text (in terms of paragraphs) often had no reliable relationship to the structure between the sentences; so, for example, a paragraph should start with the main idea, but oftentimes it wouldn't.
      3. My experience at Infer / how I organized the wiki (?) (maybe have this as a kind of high-level intro / summary of the idea?)
        1. I got this idea while working at the Silicon-Valley startup Infer, where I became obsessed with the internal wiki they were using (Confluence), and spent many, many hours organizing it and thinking about it.  Eventually I settled on a way of organizing instructions that was very step-by-step, much like when you're writing a computer program.  I found that organizing the text in a structured way made it easier for me to parse the text as opposed to when the text was just one sentence after another.  I then thought it would be interesting to explore all the ways that the management of people could be improved by applying ideas from the programming of computers.  Hence the idea for this book / audiobook / course.
    3. Talk about the existing businesses / software that are starting to move in this direction (e.g. Mechanical Turk, or detailed manuals like those that exist for McDonald's or the military).
    4. Summary of part one
    5. Summary of part two
  2. How different concepts in programming could be applied to the writing of instructions for humans.
    1. Compilation
      1. How it looks when doing people programming:
        1. Compiling from one language to another: If you have employees who don't speak your language, you might write out the process for the employees to follow in English, and then pay a translator to translate the instructions into the employees' language.
        2. Compiling from a more-complicated version of a language to a less-complicated one: the employee you're giving instructions to may speak English, but have a limited vocabulary.  So you might write out your instructions as you would understand them, and then figure out which words the employee doesn't understand and rewrite them using simpler words that the person does understand.
        3. You might compile instructions to be understood not by the people who will ultimately perform the instructions, but instead to be in the form that some other process / business is expecting; they would then perform further compilations to get it into the state necessary for the actual workers to perform those actions.  For example: suppose you speak English, and you hire a construction company to build your home, and the manager there (your point-of-contact / "API") speaks Spanish, but the actual employees who will perform the work speak French.  So you compile your instructions from English into Spanish, and the manager then does his additional work to create the final instructions in French for his employees.
      2. What the analog version could learn from the computer version:
      3. Examples of things in the spirit of compilation:
        1. XKCD - Simple Writer ← This compiles complicated English into Simple English, like how TypeScript (more-complicated JavaScript) can get compiled into ECMAScript 3 (a less-complicated version of JavaScript).
        2. Simple English Wikipedia ← This is kind of like the output of a process of compilation: people are converting the 'normal' English Wikipedia and 'compiling' it to Simple English versions.
    2. Linters
      1. How it looks when doing people programming:
      2. What the analog version could learn from the computer version:
      3. Examples of things in the spirit of human-instruction linters
        1. Hemingway Editor
        2. Grammarly
    3. Graphical user interface
      1. How it looks when doing people programming:
      2. What the analog version could learn from the computer version:
  3. (?) Ideas for businesses / innovations that this way of thinking about writing instructions for people / managing people could make possible.
    1. It might make more sense to have the ideas for businesses with their corresponding programming concept.  For example, have ideas for linter companies in the section in which you describe what a linter is and how it could be used for writing instructions for people.

Ideas for chapters/lessons

  • Give a detailed explanation of how to use Confluence to organize information for your company.  You can use your company-wide email as a starting point.
  • Go through lots of different concepts of programming and discuss how they could be used for management.
    • You could maybe use your Intro to Programming with Python course as a source of (some of?) the ideas you could cover.
  • Think about what the future of management might look like / what kinds of apps could exist in the future based on this idea.
  • Maybe have each chapter introduce a particular problem and then explain what the people-programming solution to that problem would be, similar to how your Intro to Programming course would always start with an analogy of a problem that a person might encounter in the real world while managing people.
    • This is looking to me like the best bet for how to structure things.
    • Maybe also start with the simplest possible computer and gradually build up in complexity, like in the book "Code: The Hidden Language of Computer Hardware and Software".

Misc ideas

  • For each computer concept:
    • Think about what the analog / people-programming version would look like.
    • Think about what the analog / people-programming version could learn from innovations in the computerized version.
  • Debuggers - When programming it's really helpful to step through the code, one step at a time. Similarly, when people-programming, it could be very helpful for managers to "step-through" the steps involved in their subordinates' jobs in order to get a sense of where things are going wrong. But AFAIK most managers never do this.
  • Type checking(?) - When dealing with human employees there's often a lack of standardization that makes it difficult to efficiently call for help.
    • Type checking would be for the inputs and outputs for each process, but the actual process followed usually varies from employee to employee, and even for a single employee that .  It's like if you had a sumTwoNumbers function while writing computer code, and sometimes when you called it the computer would subtract the numbers by mistake, or add them but somehow do it incorrectly so that it got a wrong answer.
      • It would be interesting to make a game where you need to write code for a computer that doesn't reliably follow your instructions, or makes mistakes.
  • Problem - Humans often don't have an efficient way of referring to a series of steps that they need to follow.  For example it's not like the next instruction they need to follow just pops up in front of their face.
    • At Amazon they have their instructions appear on a computer on their wrist.  You could also imagine it appearing on a Google-glass-type interface.
  • Tor - How would an analog version of this work with people programming?
  • Blockchain - How would an analog version of this work with people programming?
  • You should come up with a list of common problems that people encounter when managing and working as employees and how thinking about management as programming could solve those problems.  For example Yang was having trouble delegating tasks because he was not taking the time to specify how the task should be performed.  We also had trouble hiring because nobody ever took the time to specify what we were looking for in employees.  An employee's often have trouble when starting because no one has taken the time to specify how the job should be done step by step.
    • Talk about how managers often just say a correction to an employee and expect the employee to never make the mistake again, even though the manager never takes the time to write it down.
      • And on top of the employee being liable to forget the correction, the manager himself is liable to forget that he made that correction.
  • Hacking - Talk about social engineering
  • Video games
    • Think about how an analog version might work.  I guess any kind of in-person entertainment might be an example, like an escape room, theme park, paintball course, casino, etc.  You have processes for employees to follow to create the experience for the users.
    • Think about what the analog versions could learn from innovations in the computerized versions.

Products / companies / processes where you can see this trend happening

  • The US military's extensive field manuals
  • McDonald's' extensive operating manuals
  • Invisible Technologies
    • Basically they offer a streamlined way to accomplish certain tasks that many businesses share but that require some degree of human effort.  So, like, labelling photos.
  • Scale - API for Human Labor
    • I found out about them when I was on Tinder and a (probably fake) profile mentioned it at the bottom of her profile.
  • Mechanical Turk

Sources of topics to talk about / translate to people programming

  • Code: The Hidden Language of Computer Hardware and Software (Book)
  • Wikipedia
    • Check out the table-of-contents for their series on 'Software Development':
      • Core activities
        • software development processes / life cycles - "the process of dividing software development work into smaller, parallel or sequential steps or subprocesses to improve design, product management. The methodology may include the pre-definition of specific deliverables and artifacts that are created and completed by a project team to develop or maintain an application."
          • Agile development
          • Continuous integration
          • Incremental development
          • Rapid application development
          • Waterfall development
          • Spiral development
        • ...
      • Paradigms and models
      • Methodologies and frameworks
      • Supporting disciplines
      • Practices
      • Tools
      • Standards and bodies of knowledge
    • Glossary of computer science

People to reach out to to check out the book when an early draft is done

  • Balaji
  • PaulG
  • Patrick Collison
  • Patrick McKenzie
  • Sam Altman
  • Product Hunt

Full text


  • "This is a warehouse at What they call a 'product distribution center' or something like that. And there's a bunch of workers wandering around there, filling up boxes with things. But the workers really have no idea what they're doing. What the workers are actually doing is following instructions on a computer which is strapped to their wrist, which is literally telling them exactly where to walk, what to do, what to pick off the shelf, they don't have to know what it is, they just have to scan it with the little barcode and throw it in the box. And so the entire process is mediated through software, through computer software. And in fact, when you think about it, those workers, in an Amazon warehouse, are really just a kind of output device for the software developer who's trying to write code that is going to cause a box to be packaged and shipped and sent somewhere."
    • Joel Spolsky (CEO & Co-founder of Stack Overflow), keynote speech at Slush 2016 (Source)