Your Site's RSS Feed

Lessons Learned From Building a Second Brain

Mon, 15 Jun 2020 00:00:00 GMT

Introduction

Recently I participated in the tenth cohort of a class called Building a Second Brain (also known as BASB). BASB, taught by Tiago Forte, teaches a unique system for Personal Knowledge Management (PKM). It has been steadily gaining popularity over the last few years, and for good reason. If executed properly, the system can improve the process of capturing information, organizing it, and using it to generate deliverables. I took the class for the first time late last year because I was beginning a stage of my life where I needed to manage more projects and was learning quite a few new things. I knew I needed a system to manage my life, learning, and productivity.

Although I don't follow every aspect of the approach, I have still gained a lot of value from putting several elements of it in place in my own systems. I wanted to share with you what the class entails, and offer my own perspective on what has worked and what hasn't. Hopefully this will help you decide if the class is right for you, and if not, at least provide some useful information to help you with your own PKM process.

The course material is broken up into three main parts: Capture, Organize, and Share. Each one of them is important, and they all contribute to the whole of the system. But the techniques and lessons for each are relatively distinct, so I'm going to go ahead and just present them one by one.

Capture

The first, and in many ways the most important, element of this class is capture. Capture is about properly taking in all of the inputs into your life and putting them into a trusted system. Text messages, emails, articles you read, videos you watch, discussions you have, and random thoughts that pop into your head throughout the day are all things you might want to capture.

When approaching capture, there are four main questions to answer. Why, What, Where, and How should you capture?

Why

You need to have a high level reason for capturing information. If you don't have any broader objective you are trying to achieve, there is no reason to bother, it would simply be wasted time. So, what should that higher level reason be? A quote from Richard Feynman helps out here: "You have to keep a dozen of your favorite problems constantly present in your mind". Make a list of your favorite problems, the problems that feel important and significant, and as if answering them would make things better. And then why you capture should become obvious. You capture to find answers to those problems.

What

That same set of favorite problems also helps to answer the question of what to capture. If you are ever unsure of whether it is worth saving, you can always just evaluate it against your 12 favorite problems, and see if it helps answer any of them. If it does, save it, if it doesn't, don't bother unless there is some other clear need.

There are other caveats to this of course. Sometimes a piece of information doesn't fall into one of those problems, but it is valuable for some other reason. But if it doesn't fall into those 12 problems, it should probably be kinda obvious that you need it. Tax documents? Best to keep those. Random gif that was only slightly funny, probably not. You will develop an intuition over time as to what is worth capturing.

Although I liked the 12 favorite problems exercise, and I still use it occasionally, I don't stick to this advice religiously. I still capture more than I probably should in some areas, and less in others. I'm working on building up this habit, and I have found that I just get better at capturing the right amount of the right stuff with practice. It does help to have gone through that exercise though because the act of creating it in the first place framed some things in my mind. To give you an idea of what this looks like, here is my most recent list of favorite problems.

Where

Where you should capture is going to dictate a large part of how you approach the rest of this system. In terms of where, I'm talking about where the information should go. For most people, they want this captured content to be stored digitally, so the question here is what pieces of software do you want to have at the center of your Second Brain.

The most common choice is a note taking app called Evernote. Tiago uses it himself, and many of the strategies he teaches take advantage of various Evernote features. The benefit is that it has been around for many years, and has been steadily evolving. But it has downsides. It is a very hierarchical and rigid tool built around notes living in single notebooks. There is basic linking, and good formatting, but it isn't a terribly dynamic tool.

There are a number of other options used by the community. I use a couple of tools that have come into prominence in the last few years. I spend most of my time capturing in a tool called Roam Research. It has a couple of nice features that make it incredibly easy to use for free-form daily journaling, note taking, and writing. Over time I have found myself doing more and more in here, and I'm evolving my approach every day.

The second tool I use for this is Notion. This is an amazing tool for structured data. I'm still pinning down my workflows here as well, but it is good for project planning, long term tracking, and managing larger collections of things.

The most important thing though is to pick something. And Evernote is the easiest and has the biggest community out there, so unless there is something pulling you to those other choices, it is best to start with Evernote.

How

How to capture is also heavily tool dependent. This comes down to picking a couple of sources that you really care about, and finding a workflow for each of them that works for you. I care a lot about capturing from articles. So one very workflow I use is to send everything to Instapaper, and then use a service called Readwise to automatically capture highlights and send them to Evernote. A similar workflow works for books, going from Kindle -> Readwise -> Evernote. The key here is to start with just a couple of sources and practice the workflow before adding more.

The how is still evolving for me. I'm pretty happy with my capture workflows for articles, newsletters, emails, and digital books, and I'm getting better at doing manual note taking as I watch videos, but I'm still developing my approach to taking notes on podcasts, and I have almost nothing on note taking on physical books.

At this point, if you get good at these four stages, you will start to build up a collection of useful notes and valuable information. But you can't just put it all in a pile, it needs to be organized.

Organize

One of the big components of Building a Second Brain is an organizational scheme called P.A.R.A. Made up of Projects, Areas, Resources, and Archives, this scheme is designed to have a manageable number of broad buckets and a shallow hierarchy to make it easy to find a place for any piece of information to live.

Projects

Projects are actionable priorities with an end goal. If you have a project on your list, it should be something with a concrete outcome, and a deadline to either be done with the project, or at least to check in on it. A number of exercises in the course are dedicated to building up a project list that appropriately captures all of your current obligations and desired outcomes. It is important to the system to have this somewhere visible to be able to stay on top of your priorities. This list becomes a dashboard for your life.

One formula was taught in the class that really helped me here, and I want to highlight it specifically: X by Y = Z (Project by Date = Outcome). If you ever have trouble deciding if your projects are right, try to apply that formula.

Areas

Areas are actionable priorities without an end state. These are ongoing responsibilities that you need to take care of on a regular basis. This could include things like finances, family, home, your car, a role at work, people you manage, etc... One way to approach your areas is to start minimally and add to it as you find yourself creating projects that don't fall into an existing one. Every single project should likely fall into at least one area of your life. For example, if you made a project, say, to publish an issue of a newsletter, then you should probably have either a Writing area, and/or maybe a Newsletter area to store materials that will continue to be relevant in later writing and newsletter work.

Resources

Resources are for un-actionable reference materials. Categorized simply by a relevant topic, you will likely have more of these buckets than Projects or Areas. This can include anything, from art history essays, to workout plans, or anything else that could be of general interest to anybody, that you have decided to capture. There may appear to be overlap here with the Areas, but the key difference is in how personal it is to you. You might have a Finance section in Areas and a Finance section in Resources, but in Areas it should include your own budgets, financial plans, and tax statements, whereas the section in Resources might have finance software manuals, guides to budgeting, and copies of IRS guidelines for what records to save. You should generally be able to share just about your entire Resources bucket publicly without it being that big of a deal.

Divergence

For divergence the big tactic is called Progressive Summarization. This is where you go through interesting notes and make multiple passes to extract out useful information. For the first pass you bold what stands out, second pass you highlight the best of that, third pass you write out a few short paragraphs at the top of the note summarizing the content, and if you make it to a fourth pass, try and extract a sentence or two capturing the best of the summary. You don't need to do all of these at once, and most notes won't go beyond maybe the first pass of bolding. The idea is that you will stumble across these notes when looking for good ideas, and as you start to use them, you will want to apply progressive summarization techniques so that you can leave the note better than you found it. So the best notes you take will eventually have several layers of value extracted and will be incredibly useful to you.

There are a couple of other techniques for divergence that fall under the bucket of what Tiago calls Workflow Strategies. The majority of these strategies are for the convergence stage, but a couple of them apply here.

Archipelago of Ideas: Dump a bunch of thoughts on a topic all in one place to use as a launching point later
Temporary Tags: Quickly organize your notes by tagging relevant pieces of information as you find it. These tags are designed to be deleted later.
Advanced Search: Take advantage of your tools to find interesting notes.
Color Commentary: Don't just copy verbatim, take notes in your own words to develop the ideas and understand the material.
Table of Contents: Pull all relevant notes that you discover into a single outline. This will help to organize the convergence process, and give you a list of notes to work through, progressively summarize, and extract value out of.

Applying these strategies and progressive summarization, you will end up with a collection of valuable notes organized loosely in a way that will give you material needed for the second stage, convergence.

Convergence

Convergence is all about synthesizing your notes and ideas into more concrete things that go out into the world. These deliverables can be pretty much anything, from blog posts, to web apps, to entire businesses. At this stage things go from internal to external. Internal notes are incredibly loose, unstructured, and unpolished. But what you put out into the world needs at least some level of structure and polish to it. Convergence gives you that.

Most of the advice that Tiago teaches on convergence revolves around a few additional Workflow Strategies. The remaining seven are primarily about this stage of the process.

Headings first: Map out your deliverables with an outline made up of headings
Meta-Plan: This is where you plan out your plan. Try and break down the whole project into a series of more manageable stepping stones.
Status Summary: As you work you likely won't complete everything in one sitting. When you end a working session, write a note to yourself so you know where to pick back up next time.
Dial Down the Scope: Scale the projects down to something manageable. People have a tendency to be overly ambitious in their projects, so regularly attempt to reduce the scope to counter this tendency.
Context Switch to inspire creativity: It is easy to end up in a rut when stuck in the same environment for too long. Try going somewhere out of the ordinary to change it up. Obviously it may be difficult right now, but eventually coffeeshops and other public spaces can be a great way to stimulate creativity.
Remember that Function Follows Form: The form of your deliverables are incredibly important to the value that they provide. Try varying the structure of what you are creating. Reorder outlines, try alternative formats, adjust the design, etc...
Interlink Notes. During this stage navigating through your notes should be quick and painless. Link notes together that are connected to make it easier to stay organized and quickly move around.

There is one other concept that is recommended here. It is the idea of intermediate packets. Rather than trying to create one big thing, instead create a lot of little things that contribute to the broader whole. These packets should be small, and can be reused, or republished, on their own and still be valuable. What this means is that you are constantly converging into different bundles of value, that then get recycled back in and can be reused in later divergence/convergence cycles. By focusing on small packets, you get reusability, faster iteration cycles, the ability to get feedback sooner, and make it more difficult to be interrupted because the scope of current focus is easier to regain.

I haven't fully applied the above ideas yet. I have done little bits and pieces here and there, and I definitely believe in the power of intermediate packets (my notes turn into summarized information, that can then be reused as tweets, or blog posts, which can then be shared as part of my newsletter, as just one example), but I'm still working through the details of what some of those strategies look like with different tools, and when applied to endeavors such as programming. But having them in mind to go back to is quite valuable, and if you take the course, it is incredible seeing how quickly Tiago can work when applying those strategies.

Conclusion

By the end of the course, if you can apply everything you have learned, you will have a system to go from consuming information in your day to day life, capturing that information in effective ways, organizing it for easy storage and retrieval, and then taking that information and cycling it through the processes of divergence and convergence into something great.

The ideas presented are not simple, it will take work to implement successfully. And I don't believe that there is any one-size-fits-all approach to this. I have diverged significantly from the original teachings already in the way that I do things. But the methodology is sound, and there are a ton of valuable lessons to be learned. And if the community around the class is any evidence, you will almost certainly be more productive if you start following these ideas.

Book Summary: Steal Like An Artist

Tue, 21 Apr 2020 00:00:00 GMT

I just finished the book Steal Like An Artist by Austin Kleon the other day. It is a relatively short read, coming in at about 140 small pages with lots of fun pictures. But it is jam packed with good insight into how to be a better, happier, and more productive creative. Although written from the perspective of an author, the advice applies to just about any creative field.

This is a book that is well worth having in physical form because it is just so pleasant to look at! I plan to keep it around and in sight for when I just need something to flip through and get a little bit of inspiration or motivation.

It is broken down into 10 key ideas, each of which is a recommendation on how to live or work. I won't go too in depth into each one here, I mostly want to give an overview of what is in the book, and capture a very brief summary of my favorite points.

1. Steal Like An Artist: Seek out lots of good inputs and ideas in your life and steal the best ones. Every artist steals, so don't be scared to do the same, just be sure to do it well, and do so in a way that respects the original work.

2. Don't Wait Until You Know Who You Are To Get Started: Do the work to find your voice. Emulate all of your favorite people, and keep emulating until you find yourself in the work.

3. Write The Book You Want To Read: When creating, don't just think about what you already know, or what you are most comfortable creating, instead think about what you would want to see in the world. If your favorite creators came together to make something, what would you want it to be? Make that thing.

4. Use Your Hands: Get out from behind the computer every now and then. Give yourself a space to create and manipulate ideas physically before bringing them back into digital space.

5. Side Projects And Hobbies Are Important: Give yourself things to productively procrastinate on. Take time to mess around and explore a variety of interests, you never know what will connect together in useful ways.

6. The Secret: Do Good Work And Share It With People: Take advantage of early obscurity to figure out the work you want to do. Get good at that work, create things, and put them on the internet. Allow your audience to hold you accountable as you actively improve and develop your ideas.

7. Geography Is No Longer Our Master: Build a community online, find people to support you and guide you. Live somewhere that gives you the life you want. Leave every now and then, discomfort is important.

8. Be Nice. (The World Is A Small Town): Don't be mean, be nice instead. Try to be a good member of the internet community, spend time around people that will make you smarter, and give back. Avoid over-indexing on the thoughts of others; don't demand responses or validation, don't get in fights, just channel everything into doing more work.

9. Be Boring. (It's The Only Way To Get Work Done): Take care of yourself. Stay healthy, financially secure, socially stable, and organized in order to have the energy, clarity, and support to be creative and make good things.

10. Creativity Is Subtraction: Limitations are freeing for creative work. Put restrictions on yourself to get past paralysis of choice and get to work. Over time your voice will appear not just in what you include, but what you leave out.

If you want to read my raw notes from this book, you can find them at https://aengusmcmillin.com/brain/steal-like-an-artist

My Experiences With Homeschooling

Wed, 15 Apr 2020 00:00:00 GMT

I was homeschooled growing up. And not just for a few early years, I was homeschooled for the whole thing. I never went to a normal school until I headed off to take community college classes at sixteen. Until then, the closest I got was going into high schools to take the necessary standardized tests. Obviously this is a different experience than most people have, and when folks find out that I was homeschooled my whole life, they tend to have a couple of questions.

The most common ones are along the lines of "why were you homeschooled?" or "how did you like homeschool?" And then there are the people more seriously considering homeschooling their kids, who have questions about the social side of things. I usually give a short answer to these sorts of questions because I don't really feel like going into a deep analysis of my childhood with someone I'm talking to. But especially given the increased interest and necessity for homeschooling during COVID-19, I figure I should write down a few answers to these questions in case it helps anyone.

Why was I homeschooled?

There is a common concern when homeschooling comes up about the reasons for homeschooling. There is a not insignificant portion of parents who choose to homeschool their kids for religious reasons. I have been to homeschool conferences with a surprising number of creationist and bible study lectures. Some of these parents are trying to keep their kid away from anti-christian science study and give them a more conservative education. That wasn't at all the case for my parents.

There were a couple of main reasons why they took this path for me and my siblings.

First of all, my mom believed that the public school system was far too rigid in how it taught. For children who excelled in some areas but weren't quite as strong in others there was very little adaptation to allow them to lean in to their strengths and be given the space needed to find footing on their weaknesses. Plus, in many schools the teachers are essentially required to teach to the tests, which severely limits the amount of creativity and exploration that can take place in the classroom.

By taking hold of education within the home it was possible to adapt the curriculum to our individual needs, give us room to explore, and allow the space needed to excel and find our strengths.

The second main reason is that we were a Coast Guard family when I was growing up. That meant that even if we could find a good school in our local area, we would inevitably be pulled out of it, moved across the country, and have to figure out a new school in a new location every 2-4 years. And the odds of being able to find great schools for all three of us kids everywhere we went were slim to none.

Also, I should say, we were never forced to be homeschooled, it was always our choice. My brother tried out high school for a year and decided to come back, and my sister did a few years when she was younger and then went back to do the entirety of high school in the actual school system because we were, at that point, in a place with great schools for what she wanted.

Homeschooling gave us the option to take control of our education and have more consistency in our otherwise regularly changing lives.

How did I feel about homeschooling?

For the most part I really liked it! I got a great and well rounded education, grew closer to my family, and had lots of opportunities available that kids in school may not have had.

As far as the education, although it was a quite different structure than it would have been in school, my mom did her research and built a curriculum that covered almost all the bases. I was able to move quickly through math and other more comfortable subjects, and independently make progress through the books and resources. And for the things I was less comfortable with, that was where Mom could spend her time, helping me more with writing, and generally giving a more guided education with history and social studies.

And again, as was her goal, it was a very adaptable approach, when I was twelve I developed an interest in programming, and I had the freedom to spend time studying and practicing that every day. And that is just one example of the sort of educational adaptations that we were able to make. Reading is another great one. Many students in school grow to somewhat despise reading because they are assigned books, given a timeline, and told to write a book review at the end. Alternatively, for me and my siblings, we all picked up reading relatively quickly and developed a love for books because we got to select at least some of what we read, and we were read aloud to regularly as well (something I highly recommend homeschool parents try to do, it's really great bonding time!).

Outside of the curriculum-based learning, there was also more tangential learning in the form of field trips. This is something that really benefits from being homeschooled. My understanding of school trips is that you are bussed there and have a couple of stressed out adults guiding a mass of students around a zoo or museum. It ends up being chaos, and the focus is more on the kids socializing and the adults pretending there is learning happening than anything else. When homeschooling, there were just a few of us, we got input on where we wanted to go, we could go at whatever time was most convenient and would allow us to skip the crowds, and we got to go through at our own pace and spend more time enjoying the things we liked. We went to many science museums (gotta love the hands-on activities), zoos, and aquariums growing up because of this. I suspect we got a much better experience than we would have in a large class.

Now, it certainly wasn't all sunshine and roses. Even outside of the social side there were things that we missed out on.

The biggest is extra-curriculars. Although we did have sports and other classes we would go to in the afternoons, there were some of those that just weren't available to us since we weren't in the school. And we didn't necessarily have access to the same shared resources and larger spaces that are available to school students. I'm not sure there was too much we missed in that regard, but it is something to consider.

There was also a difference in academic emphasis between what we got and what students in school got. I still feel like I got a relatively solid history and social studies, but probably not as much emphasis as they give in high school for example, so there are at least a couple of topics that come up every now and then that I don't have the same context on. Again, not a terrible thing, especially since I don't believe the academic emphasis from schools is all that well designed, but this at least goes to show that it is hard to design a fully comprehensive curriculum.

And there is one more slightly odd thing that I think impacted me more than my siblings, but I have noticed it more and more as I have gotten older. My handwriting is super slow! There are a couple of reasons why I think this is. First of all, we learned italic cursive rather than looped, which prioritizes legibility over speed. Secondly, I was allowed to start typing many of my writing assignments as early as, like, eleven years old when I started getting into computers, so although I can type quickly I never focused on the handwriting skill set. And finally, I am cross dominant. So although I learned to write and do many other things with my right hand, as I have grown older I have found that my left hand is stronger in some ways. So not entirely the fault of homeschooling, but definitely a skill weaker for me due to lack of practice, and it has made it hard for me to pick up a physical journaling habit as an adult.

The Social Question

This is probably the most common concern when it comes to homeschooling. There is a picture of homeschoolers as awkward and socially inept, lacking in decent quantities of social interaction to train them. I won't say that this stereotype is entirely invalid, and I may not be the greatest counterpoint myself, but there are a lot of contributing factors here and it isn't like homeschooling is a social death sentence.

The thing about homeschooling is that there actually are plenty of ways to socialize. There are homeschool groups, they can still join sports, and depending on location there may be an active group of kids right in the neighborhood. The difference with homeschooling, is that socializing needs to be more actively pursued, rather than passively happening due to the environment.

And I will say, there are plenty of perfectly well adjusted homeschoolers that I met growing up. They may still have been slightly out of the ordinary in a variety of different ways (a definite side effect of not going through a standardized system), but the majority of them were quite outgoing, friendly, and easy to get along with.

One thing worth considering are the external factors that might impact social life. For myself, although there were a number of benefits to homeschooling as a military kid, it definitely made things harder basically needing to reset every 2-4 years. Especially since as an introvert I have always had a tougher time meeting people, the fact that I was also forced to reset so frequently and didn't necessarily have an automatic group of people to spend time with certainly made it more difficult to find friends, especially as I got older. But again, there were several other factors that contributed to my situation, the homeschooling was just one part of it.

Should you homeschool your kids?

I'm hoping I have given a little more insight into both the good and the bad of actual homeschooling. Given the current COVID-19 situation, there may be a number of you reading this currently going through stay-indoors-at-homeschooling. I want to tell you that that experience isn't what normal homeschooling is like. With traditional homeschooling you would have time to prepare a curriculum. You are able to plan fun activities and excursions. You can leave the house and get outdoors and send the kids off for an hour of two at a class with somebody else taking care of them. “Normal” homeschooling isn't easy, and it isn't without its flaws, and it certainly isn't even an option available for everyone, but if you can make it work, and if the tradeoffs sound worth it, it can be a really great thing.

Writing About What I Know

Sun, 12 Apr 2020 00:00:00 GMT

I want to create more Living Document style pages outlining topics I am learning and am familiar with
These won't be tutorials, they will be more of a Reference, a way for me to outline the most important elements of these different tools, languages, and frameworks in a way that makes sense for me
I should be able to visit these posts whenever I know I have encountered a problem before and have a good likelihood of having written it down. This will include things like common syntax mistakes I might make, forgotten git incantations, or the different ways to center something in CSS.
I also want to eventually integrate my Anki solution into the things I have written here to integrate what I know into my memory a bit better
I am inspired to do this by the numerous other folks who regularly teach topics as they learn them (Tania Rascia, Jason Lengstorf among others), posted their notes publicly (Nat Eliason, Andy Matuschak), and otherwise spread the gospel of learning in public (folks like David Perell and swyx)
There will likely be a number of mostly empty posts going up, I want to get a framework in place now, and build it up as I go.

Kotlin Part 3: Control Flow & Equality Comparison

Fri, 10 Apr 2020 00:00:00 GMT

Welcome to part 3. Last time we got some basic printing and user input happening and went over variables. But now, we need to actually start doing different things depending on what the user types. In order to do that, there are two concepts that I want to introduce: control flow, and equality comparison.

Control Flow

Control flow is controlling the order in which the code of your program is executed. Examples of control flow include looping through statements more than once, branching between several different options, and returning early from a function. I will be going through most of these throughout the series, but for now I want to focus on one in particular: branching between options with If Statements.

If Statements are a way of evaluating the state of your program, and choosing between several different code paths to go down. The way it works is that you pass a Boolean condition to an if statement, and follow that up by a block of code that will be run if the condition is true, and optionally an else block that will be run otherwise.

val condition = ... // Some boolean result

if (condition) {
    println("condition is true")
} else {
    println("condition is false")
}

It is also possible to chain if-else statements to branch between more than two options.

val condition = ... // Some boolean result
val condition2 = ... // Some other boolean result

if (condition) {
  println("condition is true")
} else if (condition2) {
  println("condition2 is true")
} else {
  println("neither condition is true")
}

We will be using if statements to evaluate the selection and decide what to do next, but before we can do that, we need to actually be able to determine what the user entered. To do that, we need equality comparison.

Equality Comparison

Equality comparison is exactly what it sounds like, comparing things to see if they are equal. To do this we are introducing a new bit of syntax, the double-equals == equality operator. What the equality operator does is compares the left hand side vs the right, and returns a true Boolean value if the two sides are equal, and false otherwise.

Examples

val integerComparison = 2 + 2 == 4
println(integerComparison) // prints true

val bool1 = true
val bool2 = false
val booleanComparison = bool1 == bool2
println(booleanComparison) // prints false

val stringVal = "foo"
val stringComparison = stringVal == stringVal
println(stringComparison) // prints true

Because the equality operator returns a boolean, the result can be passed to an if statement to do branching. This is what we will be doing in our code. A simple example might look like this:

val input = readLine()
if (input == "say hello") {
  println("Hello World!")
} else {
  println("I don't know what you want")
}

Branching User Flow

Now we are ready to apply the concepts above to our program. You should hopefully understand the rough idea, so I'm going to present a block of code showing the new state of the 'main' function, and give a brief summary of what is happening.

fun main() {
    println("Welcome to Alanor. You have just arrived from Terra on the Gamma 6 shuttle.")
    println("")
    println("Immediately upon stepping out of the shuttle you notice that the air is thinner")
    println("than on Terra, and the gravity ever so slightly stronger. This will take some")
    println("getting used to.")
    println("")
    println("In the shuttle station, along with a variety of other passengers arriving")
    println("with you or waiting for another shuttle, you see an *exit door*, a")
    println("*vending machine*, and a *bathroom*. What do you want to do?")

    val selection = readLine()
    if (selection == "exit door") {
        println("You walk to the exit, open the door, and walk out into the light of the two")
        println("suns of Alanor. You are immediately met by someone you recognize as the recruiter")
        println("who hired you for the position out here.")
        println("")
        println("You join them in their car, and head out for your new life on a new world.")
    } else if (selection == "vending machine") {
        println("In the vending machine you see some very boring looking fare. There are *chips* ($20),")
        println("some sort of *candy* (\$30), and *nutrient paste* (\$50).")
    } else if (selection == "bathroom") {
        println("You see three sinks with mirrors, and a bathroom stall with a closed door.")
    } else {
        println("Unhandled selection: $selection")
    }
}

The first section of println statements is the same as last time, the difference comes after taking in the selection. Last time you simply printed the selection and returned. Now we are using control flow and equality comparisons to branch, and take a different path depending on what the user enters.

If you run this a few times, you will see that you can type one of the options and the program will respond appropriately. From our spec in the last post, this mechanism is the bulk of the program! If you wanted, you could just about brute force the entire thing with nothing more than you have already been shown.

There are a couple of problems still though. Already you can see that this main function is starting to grow and get a little bit complicated. Imagine what will happen when you begin introducing more options, and introducing further branching down each chain? Plus, we don't currently have a way of backing out of an option and going back. So, for example, when the user is done at the vending machine, there is no way of going back and asking where they want to go next without duplicating a bunch of println statements.

Both of these issues will be solved in the next couple of lessons.

To first issue will be solved by introducing structure into the program with classes, and the second will be solved by combining classes with new type of control flow: loops.

Book Review: Bird by Bird

Wed, 08 Apr 2020 00:00:00 GMT

In Bird by Bird, Anne Lamott presents an interesting volume about writing. Although her focus is on fiction, much of the advice and ideas are applicable to other types of writing as well. As someone working to get better at non-fiction blogging, the advice has aligned well with other things I have learned, and has helped reinforce much of what I know about being a good writer.

Clocking in at about 240 pages, with a great combination of useful advice combined with wit and colorful storytelling the book is an enjoyable read all the way through. Anne includes many personal stories about her life to provide visceral examples of the lessons she is giving and make it clear that she, and just about every other author, struggles with many of the same difficulties.

Best Advice

Although there are numerous topics covered in the book, there are a couple of key topics that came up over and over throughout. These ended up being some of the best takeaways:

Take notes

A huge part of writing comes down to having enough material to draw from. Take notes on the hardships in your life, take notes on interesting things you see or hear, take notes on ideas that come to your head, take notes on everything. Anne describes keeping a folded up index card and a pen in her back pocket wherever she goes, generating scattered piles of ideas all around her house to draw from. Notes don't necessarily need to be detailed, they just need to be enough to invoke the memory of what you are capturing.

Put in the hours

At every stage of writing and publishing you will have self doubt, anxiety, writers block, and other barriers that make it difficult to create. For the most part the best approach is to sit down every single day and get down at least few hundred words. That will unblock you, help you get past the barriers you are facing, and allow you to build the writing muscle and defeat perfectionism. If you don't know how to put in the hours, pick short assignments for yourself and write shitty first drafts.

Tell the truth

Story telling is all about telling the truth. Find your voice so you can tell your own truth, dig and uncover and get to know your characters to learn about their truth and tell that, ensure that the narrator of the piece is a truthful figure. Work as hard as you can to understand your world and the world you are creating, and tell the truth as you understand it.

Work with others

Find a writing group to keep you accountable. Get trusted people in your life who can review your drafts, and if they are writers review theirs in turn. Reach out to people to learn more about what you are writing about because, again, you are trying to tell the truth, and in order to do that you need to understand what you are writing.

---

There are other tips throughout the book on character development, building plot, and writing dialog, along with stories and advice about dealing with the hard times of writing and publishing, building the right mindset to approach the craft, and getting your brain to shut up and do what you want it to a little more often.

Personally, my biggest issue with the book is that, as someone who doesn't plan to write a novel or anything of that sort, a fair bit of the advice wasn't for me. The character development and dialog sections aren't super applicable for me, and some of the advice is about working through the creation and publication of very long pieces of work (e.g. books) which I won't be doing anytime soon.

But overall quite an enjoyable book, and if you are a writer, especially a fiction writer, I would recommend giving it a read.

P.S

I have been trying to take more thorough notes on the books that I read and have begun setting up a section of my site to upload these raw notes. You can find my notes on Bird by Bird here.

Artificial Accountability

Sun, 05 Apr 2020 00:00:00 GMT

When sitting down to get work done, trying to follow through with a daily routine, or finding time to practice a new skill, it can be easy to get distracted. Your phone buzzes, or you get a notification, or you just feel a few moments of boredom and open up social media. Whatever the situation, it can easily turn into far too much time wasted.

One benefit of an open workplace is that there is some level of accountability from the presence of coworkers to not do much time wasting. You know that the occasional glance at your phone is fine, but people might start to wonder what you are doing if you stare at it for 30+ minutes! But many people don't work in that type of environment. It is hard to get the same effect when working from home.

This was one of my biggest challenges with productivity after I quit my job last year. It took more effort for me to stay on task and avoid getting distracted because I had no external accountability. And given the current Coronavirus situation I'm sure there are many other people facing similar difficulties now.

Now, you could try and get a friend to help be an accountability buddy, but then you need to make sure they have a way of being aware of what you are doing, and you need to get somebody to help with your problem. So is there a way to establish an artificial accountability system without pestering friends?

Enter, Toggl

I didn't quite make this connection at first, but recently I recognized that timing apps like Toggl can fill this role. I have been using Toggl more and more the last few months, but then about two days ago I ended up in a funk one day and just stopped using it and didn't start back up for about four days. During that time I realized that I was way less productive than I had been, but when I started back up immediately I started getting more done.

What I realized is that Toggl had been filling the role of an accountability partner. I had to tell it what I was working on, and it was keeping track of how long I spent on that task, which made me feel a certain amount of guilt if I did something other than what it was measuring. And I certainly didn't want to stop my writing timer to tell Toggl that I was browsing Reddit, that would feel crazy!

A similar result is completely possible to achieve with other solutions. I have recently switched to using a Daily Log system within Roam to do my timing in a way integrated into my journaling and idea capture. It works almost as well, although admittedly without the active timer counting up it is slightly less compelling of an accountability factor. I might need to start incorporating the Pomodoro technique again to add back in the active counting element.

what the daily log looks like

Alternative Approaches

There are ways of introducing artificial accountability beyond timer apps, and it is worth trying different options to find the best one for you. Whatever you do will need to be based on your own way of working, thinking, and behaving. There is no one size fits all method here.

One approach could be to encourage you to hold yourself accountable with a reward system. For example, if you keep yourself under a certain number of hours of social media time, you could reward yourself with a donut at the end of the week. Or reward yourself with a certain amount of video game time at the end of an otherwise productive day.

Rather than a carrot, you could also try a stick. Beeminder is a popular accountability system that allows you to track certain metrics using the site, and can have it automatically take money from you if you fail to follow your goals closely enough.

There are likely numerous other approaches out there, and again, try different options until you find out what works.

Rules of Engagement

Whatever approach you take, there are a few rules that can greatly increase your chance of success.

Do a bit of planning and/or time blocking at the beginning of the day to know what you are supposed to be doing. This can be as high level or as detailed as you want, but having a plan will make it easier to know what to do next whenever you are ready to start a new timer and move on to something else.
Be reasonable with yourself. Don't be overly strict or rigid with your approach or you will begin to mistrust your system and won't care as much if you ignore it.
Make it hard to ignore. Keep a tab open somewhere with your timer running. You don't need it to be so visible as to be distracting, but make sure that every so often you will see it and remember that you have a system going.

With the above approaches and rules you should be able to conquer distractions and get more of what you want to out of every day. That is the power of artificial accountability.

Android Basics: Introduction

Fri, 03 Apr 2020 00:00:00 GMT

Welcome to my Android Basics series! Throughout the coming posts I will introduce you to the fundamentals of building a high quality Android app from scratch. Starting from an empty Android Studio project, we will build out an entire app, following solid development practices, designing a good architecture, and targeting relatively high quality UI and UX to make sure the app comes out the other end as a great piece of software.

What will we cover?

Throughout this course I will teaching:

Fundamental Android concepts such as Fragments, Activities, and Views
How to architect an Android app for easy maintainability, testability, and extensibility
Tips to effectively use Android Studio to build an app (I will be using IdeaVim, but will include plenty of non-Vim tips as well)
Android modularity
Unit and integration testing
How to properly handle errors and give feedback to the user about incorrect inputs or failure state
Dependency injection, a summary of the available options, and then details about using Koin throughout the rest of the series
Planning out a data schema and using Room for databases
How to build a UI, including details on building custom views, how to present data in a list, and how to properly style your app
Little ways to improve the experience of using the app. Everything from audio feedback to interaction animations.
How to share with other apps
How to prepare an app for the Play Store

There are many details of app development that won't be covered. There will be minimal use of media (only for UI feedback), no complex networking, and the interface will be relatively simple. This will also be a free app with no IAP, so I won't be covering any payment processing topics

In the future I will be writing series delving more into these unexplored areas, but for now even with a relatively simple app this will be a lot to cover!

Prerequisites

This is not a series for totally beginner programmers. I won't be covering Kotlin basics, I will be going quickly through much of the tooling setup, and I will expect some familiarity with Git and other basic development tools.

If you are completely new to Kotlin, I would recommend taking a look at https://kotlinlang.org/docs/. The Getting Started guide on the official docs should give you enough background to understand what I'm teaching.

I won't expect any prior knowledge of Android development though. This will literally start from the installation of Android Studio and go from there.

What are we building?

As I have discussed before, I will be teaching with projects that are at least somewhat compelling and could be interesting to use. As such, I want to build a habit tracker app that captures the idea of 'don't break the chain', and presents it in a nice way. Ideally this should be an app that is satisfying to use and you will want to have on your own phone. The working name for the app will be HabitChain.

I will say though, if you aren't feeling that inspired by HabitChain and have an idea for a similarly scoped project, feel free to build that instead! There will of course be adjustments you will need to make, but the process should work relatively well, and at worst you might need to repeat some things a few times to build out all of the features in your app. But if it keeps you more engaged with the material you will learn much more, and adapting the learnings to something of your own is valuable in and of itself.

Next Steps

In the next lesson I will be introducing some basic concepts, tools, and terminology that you will come up constantly as you develop for Android.

Next Post: Coming Soon

Music: A balance between novelty and comfort

Thu, 02 Apr 2020 00:00:00 GMT

We love music because it ties in repetition, familiarity, and predictability with a sense of creativity and excitement. Those first three elements are crucial because they give us a sense of comfort and satisfaction when we are listening, and generally make us happy. There are many rules that have been developed throughout history that work towards establishing and codifying those elements in every genre and style of music imaginable. But when music is overly repetitive, familiar, or predictable there is a risk of boredom. If music is perfectly predictable it is no longer exciting, if it is completely familiar it no longer feels creative! What we need is for some amount of novelty and variability to be introduced to keep it exciting and maintain that creative feel that makes us want to keep listening and finding new music. There needs to be a balance found between the tried and trusted rules to keep us happy and satisfied, and enough variability and novelty to keep us interested.

What is variability?

Because I'm going to be talking about this quite a bit, I want to clarify that I'm not talking about any specific pre-existing musical term when I talk about variability. What I'm talking about is any element of the music that feels slightly surprising, unexpected, or out of the ordinary. It could exist in the vocals, the melody, the choice of instruments, or anything else.

How to find the right balance?

Variability is something that needs to be handled with care. People have different tolerances for it. Apply too much and you might scare them off or 'offend their sensibilities', creating music they don't enjoy listening to. Apply too little, and they will get bored and move on to something different. As a musician you need to have at least a basic understanding of your audience and what they might expect and want. This is especially important for established musicians trying to expand their discography. If you completely break away from what you have done before, there is the definite risk that the new music won't sound good to people that enjoyed your earlier work!

It's also worth considering the differences in tolerances between different populations, as well as the tolerance in certain genres. Pop music is as successful as it is because it has selected a level of variability that is within reasonable bounds by nearly everyone. Nobody is heavily offended by the musical choices made in a pop song, but people can get a little bit of variability with interesting lyrical choices and differences in vocal quality, even if the instrumentals, rhythm, and chord progressions sound rather similar between many of them.

Lots of alternative music though, although it has a following, may not ever be quite as mainstream because it makes more contentious choices. Artists like Dakha Brakha use very unique instrumental decisions and the vocal expression is different than most other bands. This doesn't make them any less great, and they still have a large fan base, but it means they are less likely to take off and be played on stations across the country compared to a pop star.

How to Introduce Variability

Variability can be introduced in a couple of different ways. First of all, you can simply break the rules. Take a formula you are familiar with and intentionally don't follow one part of it. For example, in the David Bowie song Space Oddity, he intentionally plays an A major chord instead of an A minor chord despite being in a C major scale (basically, he plays a grouping of notes that is outside ). This is breaking a rule, but it does so in a controlled way that sounds great!

Secondly, you can combine different rules and patterns in unexpected ways. Take a rhythmic and melodic formula that is most commonly used in jazz and mix it with country music instruments and lyrics. There is an entire genre of music, electro swing, designed around taking some of the patterns originally build for swing music, and introducing electronic music instruments, synthesis, and patterns into it.

And finally, you can introduce elements that simply aren't as commonly heard. Add in an instrument that people aren't super familiar with, use a chord progression that isn't as common, or even just write lyrics that keep people engaged and intrigued. The band Katzenjammer uses a huge variety of instruments in their music, including one (the balalaika) that is incredibly uncommon.

There are lots of different ways to accomplish this variability, but most of it comes down to understanding the rules of music and finding ways to vary them.

Make It Sound Good

All of the above is good to consider when building a piece, but it's worth remembering that there is one thing above all else that matters in music. It has to sound good! You could have as much or as little variation on the rules as you want, but if you have chosen the wrong rules, or don't apply them effectively, your music won't sound right, it won't make people happy, and your song won't succeed.

So whatever else you do, make it sound good!

Basic Anki Workflow

Wed, 01 Apr 2020 00:00:00 GMT

I wrote about spaced repetition systems (an approach to better learning and memory) recently, and in there was a brief section about Anki. I wanted to expand upon that and provide a guide on how to setup and use Anki, and provide a couple of tips and tricks as well.

Initial Setup

Getting started is super simple, go to https://apps.ankiweb.net and follow the steps to download and install it on your (mac, linux, or windows) computer.

Once you have it installed, open it up and follow the steps to select a language. Once that is done you will be presented with a screen similar to this one, although the name of the deck might be Default. You can rename this if you want, but it isn't necessary. With that, you are all setup!

Organizing cards (and why you shouldn't)

In this guide I'm demonstrating a super simple single deck workflow, and not because I'm lazy, but because I think it is the best way to go and this is the system I'm using. It is possible to organize your cards into a variety of different decks based on topic and subject matter, but there are a couple of advantages to keeping everything into a single deck.

First of all, simplicity is valuable. Using Anki is something that should begin to become a habit, and when trying to establish a new habit, you want to minimize the number of barriers to pass and decisions to make when executing on that habit. If you have to figure out which deck to add to when creating cards, and which deck to review when doing your reviews, even that little bit of extra friction can make all the difference.

Secondly, you should be reviewing all of your cards regularly, and having the choice between decks makes it easier to skip ones you aren't feeling at the moment, and can lead to bad habits. And it makes it harder to manage the reviews because you can't just click one button and review until done.

And finally, by having everything in the same deck, it works the brain more and builds different connections going between different topics. There is the chance that jumping from a historical fact into a statistical question might lead to some interesting links that would otherwise not be made.

The one situation where I would recommend having a separate deck is if you decide to pull in community made cards. There are great collections out there for everything from medical students to language learners, but if you decide to pull those in, put it in a separate deck. It is possible you will only find out after the fact that the cards aren't quite what you need or are ready for, or there are simply too many, and by putting them into your main deck you run this risk of polluting the whole thing.

Creating Cards

Although Anki supports a variety of different card types, and even allows you to create your own, but in the beginning I would recommend focusing on just two, for the sake of simplicity and consistency.

The first type will probably make up ~90% of the cards you create. It is just the 'Basic' type, the default one that is selected the first time you click the Add button to create a card. It is incredibly simple, has a field for the front of the card to put a question or prompt, and a field for the back to put an answer.

example of creating and reviewing a Basic card

The second type is the 'Cloze' cards (based on the Cloze test). These are essentially just fill in the blank cards. Rather than having a field for the front and the back, instead there is just a single field for the text. In this field you will write out a statement (e.g. In 1492 Christopher Columbus landed in the Caribbean), and then highlighting sections of it, clicking the [...] button to turn them into clozes. Then when you hit 'Add', Anki will create a card variant with each of the clozes blanked out to fill in (so for that last example, you could add a cloze around 1492, Christopher Columbus, and Caribbean, and Anki would create three separate cards asking to fill in each of those).

example of creating and reviewing a Cloze card

Tips & Suggestions

Avoid pulling in too many of your cards from other people's decks. There is a lot of value in writing the questions and answers yourself, it forces you to frame an idea in your own words, and those words are then something that will resonate more strongly with you when reviewing later.

Try and complete a review every day. This is a system designed around well spaced reps, and if you skip too frequently it won't have as good of an effect. Plus, if you don't, eventually the backlog will start to build up and it will become harder and harder to get caught back up. If this happens to you, don't worry, just go into the settings and adjust the number of reviews per day until you are caught up (gear icon next to deck -> Reviews -> Maximum reviews/day).

Figure out triggers for yourself to remember to capture things into Anki. This is something I'm definitely struggling with still, but one approach I'm taking is when I'm done reading and taking notes on an article, I will go back over my notes and try to think of anything worth explicitly remembering.

Anki for mobile

Anki is also available for your phone, which can make it much easier to capture on the go and review in short bursts when you have time but don't have your laptop. There are two separate apps, there is the paid AnkiMobile app for iOS and AnkiDroid for Android.

Again, both should be pretty easy to setup, the main thing you will need to do is make sure to have an account setup at https://ankiweb.net/. Once you have that, you can login on your computer and phone, and keep the cards and review status in sync.

The same recommendations as above apply to mobile as well when creating and reviewing.

Challenge: Three Months and a Day

Tue, 31 Mar 2020 00:00:00 GMT

Since finishing Write of Passage this past Wednesday, I have already found that I have been writing less frequently this last week. Without the pressure of the class, and without the need to attend several live sessions every week I am finding it very easy to skip my daily writing habit. I'm still writing enough to publish a post and a newsletter, but the hours spent on that don't need to be evenly spread out throughout the week. That is leading to a lack of consistency in my writing that I'm not crazy about. After reading https://nesslabs.com/100-articles-100-days, I was inspired to do my own consistency challenge: Three months and a day.

From now until the end of June, I will be striving to publish something nearly every single day. I know that there will be setbacks, and some days it just won't get done, so I am shooting for roughly a 90% success rate. Rounding it a bit, I am setting a target of at least 80 posts published by the end of June. There is no criteria on what I post, so I expect it to be a wide variety of content, from book summaries some days, to software tutorials on others, with write-ups about things I know (or want to know) scattered around here and there.

There are a couple of key objectives that I'm hoping to get out of this challenge:

Pin down my personal monopoly (concept from David Perell). I have a rough idea of what this is, but I know that this will start to solidify as I write more and identify what I enjoy writing and what I don't. Originally I figured it would be a slow but steady process to pin this down, but I'm thinking if I can publish eighty posts by the end of June I can expedite the process a bit.
Get better at writing short form content. Even in the WoP assignments to write shorter posts, mine tended to expand to take up ~1500 words minimum. This isn't crazy long, but I want to have some of my content be more focused ideas. If I'm going to be going from draft to publishing within a single day, I don't have a choice, I will have to keep the posts short and focused.
Generate more ideas. Roam Research is helping a bunch with this already, but I'm not applying the generation effect enough to really get as much value out of it as I can. But if I have to publish every single day, I will need a lot more ideas, so this should be a forcing function to get me to capture more, curate better, and take the time to use what I have.

This isn't going to be an easy challenge. In order to get it done I am attaching an hour of writing onto my morning routine. That alone may not be enough to do what needs to be done, but at the very least it is enough to write a draft that I would be scared to publish as-is, which will encourage me to go back and edit throughout the day since it will be getting published in the evening either way.

With a routine to push me and the objectives to guide me, I'm looking forward to really putting the blade to the grindstone and honing my writing over the next few months. The Three Months and a Day challenge has begun.

Teaching Programming with Authentic Projects and SRS

Wed, 25 Mar 2020 00:00:00 GMT

Introduction

As I teach programming, there are a few learning techniques I want to incorporate that I haven't seen integrated into other learning resources.

I will admit, this effort is a little bit selfish on my part! These are elements that I personally would want to try and incorporate into my own learning, and I'm very much hoping that by teaching in this way I can learn the subjects more deeply and become a better programmer myself.

Focus on Complete and Authentic Projects

Currently, the vast majority of educational material for programming falls into one of two camps. Either it is too deep without necessary breadth, or it is too broad without enough depth. For example, it isn't uncommon to find tutorials that talk about how to build an entire app from scratch. But those tutorials tend to skim over error handling, exclude effective testing practices, and generally don't give a good picture of all the nitty gritty details that make software production ready. On the other side, you will have resources that dive deep into error handling, or testing, but not in the context of any complete project. For example, nearly every single article on testing I have seen seems to come up with some contrived banking example that doesn’t feel like it would translate to anything I would ever build. There are some resources out there that give a good deal of both breadth and depth (FrontendMasters for example, has 10 hour workshops that seem to dive quite deep while also building out full websites or apps), but that doesn't seem to be the norm.

But by focusing on the right type of projects this can be solved. There are three guidelines I will be following to ensure the projects feel authentic (e.g. like a real project, rather than something that is clearly a tutorial project) and give the student a complete picture of development:

Avoid overly simplifying subjects, instead start with a project that is within an achievable scope for the student.
Don't skim over elements that would be important in production software. For example, make sure that a version control workflow is introduced early and regularly used, ensure that error handling is done properly, and incorporate unit and integration testing to a reasonable degree.
Don't skip steps that would be handled by the programmer. Start with the creation of the project the normal way it would be done, don't give a bunch of starter boilerplate. The only thing I might provide is a design spec. For some tutorials I will treat it as if there was a designer on board providing resources. Although I will eventually get more into the design side of things to teach from the perspective of a solo developer.

If I can follow these three rules it will be very easy to write tutorials that will give the student deep insight into what software development is like, rather than simply teaching them how to program.

The final part of this approach is that the student has to apply it beyond what I have taught. After every project I want to give a similarly scoped homework assignment that will be within their grasp and allow them to apply some level of creativity and flair.

Students should come out of these tutorials with experience building real programs, and even with a couple of pieces of software that could theoretically be publishable if they chose to take it the rest of the way. ⁽¹⁾

Spaced Repetition Systems

I have recently been on a bit of an SRS kick. SRS is a system for showing flashcards at a steadily increasing interval, in a way that helps with memorization and learning. After spending time digging into how it can be used, I have decided that I want to incorporate it into my tutorials. Again, this is a somewhat self-serving approach, I personally want to start incorporating more coding concepts into my Anki deck (Anki is probably the best program for spaced repetition currently), so what better way to do that than to think about it as I'm writing tutorials? Using Anki to reinforce these concepts will help with recall and improved learning.

I could leave it up to the individual to just store these things as they learn, but I have found that for myself, it's incredibly difficult to build up a habit around note-taking and capture. Without some trigger to remind me, I don't tend to think about capturing these things into Anki as I go. By incorporating triggers into the tutorial directly, it will be much easier to get in the habit of saving snippets of concepts, syntax, and important details to remember. And hopefully this capture habit will extend beyond these tutorials and help with other learning!

I would highly recommend trying to tack on an Anki review onto something that is already a daily habit. If you can stay on top of it you can build up a massive library of notes and keep them all well-established in your mind without more than a few minutes of review per day.

Someday/Maybe: Supporting other learning styles

Eventually I would like to create youtube videos for the audio/visual learners, and do some basic sketchnotes of concepts to incorporate into both videos and posts to help the visual learners, whether they prefer to watch or read. This is still beyond my current skill set though, so for now I'm focusing on the writing and teaching, and will try to introduce more varied media later on.

I want to eventually incorporate a livestream of myself working through the homework programs. Another element that is missing from programming is seeing the mistakes made. I will try and incorporate some of those into the tutorials, but seeing me live-code some of these projects will be a very different level of insight that could be valuable for the students↩

Better Learning with Spaced Repetition

Wed, 18 Mar 2020 00:00:00 GMT

I would take a bet that every single one of you reading this post right now has at least a handful of new things that you are trying to learn. And whether practicing new skills or studying concepts, a significant part of the process will require applying memory.

In my own experiences learning to play ukulele I have to remember chord positions and how to play different songs, learning Spanish requires memorization of grammar and vocabulary, even mastering more conceptual skills like writing or entrepreneurship demands the internalizing of learnings and ideas.

There are a countless number of different approaches to improving memory and learning that have been developed, but my favorite, and the one that I believe has the most potential, is spaced repetition.

What is Spaced Repetition?

Spaced repetition is a system, generally based around flashcards or a digital equivalent, for learning and memorizing information. It applies an algorithmic approach to learning and reinforcing concepts. At a high level, what the algorithm does is it shows newer and more difficult concepts more frequently, and easier and more well understood concepts less so. This means that the system ensures you spend more time practicing the things that you still need to work on, and doesn't waste time on the things you don't. Makes sense right?

SRS was first formally tested by Thomas Laundauer and Robert Bjork in 1978. A test, run with a group of psychology students, showed that the students had better face-name association after applying spaced repetition. Since then, the technique has been researched heavily for use by Alzheimer's patients and has proved helpful for people with amnesia and other memory diseases. It has also been built out into several physical and digital algorithms and tools, and incorporated into numerous educational approaches over the years.

The most popular physical approach was developed by Sebastian Leitner, the Leitner system. You have several different boxes of flashcards to study, each with a successively longer practice interval. Whenever you successfully answer a flash card you move it to the next box in the line, and whenever you answer incorrectly, you move it to the first box. This is a brute force approach that implements the SRS algorithm in a basic but physical way.

So, for example, if you were trying to memorize the capital of Iowa, you would create a card for "What is the capital of Iowa?", with "Des Moines" on the back, and start it in the first box. Then, every day you would try to answer that question. If you answer incorrectly, you would put it back in the box, but if you succeed, you would move it to the second box. Then you wouldn't revisit it for another two days, and if you succeed you move it to the third box and don't try again for another three days. And at any point if you answer something other than Des Moines, you move the card back to the front of the box and restart the process. Voila, memory training with physical flashcards!

There are also quite a few digital systems with similar functions. The most popular is Anki. It does a very similar process but hides the boxes and just delivers you cards that you need to study. Because it is digital there is a community that has been built up around sharing card decks, so you can go in and find a deck for Spanish vocabulary, state capitals, or just about anything else you might want to memorize. And the great part about Anki is that, unlike the Leitner system, it can adapt the interval of study for each card individually depending on the configured settings, difficulty of the card, and how easy it was to get the right answer. This means it can create a custom tailored study session every single day for all of the information you need to work on.

Card to try and answer

Card after answering

There are also a couple of dedicated language learning systems that apply very similar techniques. Memrise uses SRS almost exactly, and Duolingo has a slightly different spin but applies fundamentally similar ideas.

Uses for SRS

Now that you know what SRS is, what could you apply it to? Well, pretty much anything that requires memorizing things or building a deep ingrained understanding of a topic. People apply spaced repetition systems for practicing basic trivia and factoids, learning new languages, studying for exams in college, and for testing understanding of complex topics.

Recently I read an article How to Make Yourself Into a Learning Machine, interviewing Simon Eskildsen about how he learns. Part of his system involves saving tons of information into Anki and using spaced repetition to memorize it all. At this point he has over 10k notes, containing lots of random tidbits of information. There is a section of the post that I really like for why this sort of memory training is important:

"I think memory is underrated. For example, memorizing all of the U.S. presidents is something that people might think is for show. But to me it’s actually really helpful to know who was president at a certain time because it allows you to connect the president with that time period. For example, take Reagan. If you know when he was president, you can say, Okay this was around the Cold War and it was towards the end of it, and his platform supported trickle down economics which was a very important idea in that time period. Memorizing these things means that if you’re talking about the U.S. in the 80s, you’ll remember that he was president, and all of those concepts come up."

It really captures the value of this sort of system (and convinces me that I need to step up my own SRS system). This sort of memorization can improve the way you think about the world, and give you ammunition to communicate and discuss topics more effectively. It can expand your world in interesting ways.

Personally, I am still exploring how I most want to use SRS, but I do use it heavily for language learning. I started using Duolingo again near the beginning of the year, and spent about a month and a half re-learning Spanish before visiting South America. The regular reinforcement of terminology, phrases, and grammar from daily use and repetition helped a ton, and although I had taken a few semesters of Spanish in the past, just a few weeks of consistent spaced repetition did far more to help than those classes did.

Unexplored Opportunities

There are a couple of seemingly untapped opportunities in the realm of spaced repetition that I haven't seen explored. I believe that there are ways to expand SR systems beyond how they have been used, either with different technologies, strategies, or educational approaches. In doing so the educational landscape could be changed significantly in several different fields.

The main area that I don't see SRS applied is in muscle memory based practice. There are lots of different ways that music is taught, and obviously repetition is a big part of practice (e.g. practicing scales), but actually spacing out the repetition in an algorithmic way and having a system for figuring out what you should be practicing on a given day? As far as I know it hasn't been done. There are definitely some tricky aspects of this, for one thing, muscle memory behaves differently than normal memory, and there are ways the system may need to be adjusted to accommodate that. Plus, determining a 'successful answer' is more complicated with things like music practice. You might be hitting the right notes but not hitting them cleanly or consistently. This system would likely require some self evaluation and the ability to be a little more subtle with the corrections. Definitely not easy problems, but I think if they could be solved this could really change the way people approach music education.

I would also be interested to explore ways in which project focused learning could be combined with SRS. Spaced repetition works great for lots of smaller discrete elements, but I haven't seen it integrated alongside larger practice projects. For example, how could one approach using an SRS based program for teaching software development or writing, areas where applied project based practice is key?

Conclusion

Hopefully by now you are convinced to start building out a spaced repetition system for yourself. Start using Duolingo to learn a new language, begin building up a deck of interesting facts in Anki, or get yourself a bunch of flashcards and a couple of boxes if you want to be a bit more tactile with it. Try it for a while and see how it helps, it may change the way you view and interact with the world.

And one more thing, if you find other interesting approaches/tools to SRS, or find ways that it helps you, tweet me at @aengusmcmillin, I would be very interested to hear about it!

Networking for Game Development

Wed, 11 Mar 2020 00:00:00 GMT

Introduction

Video games can be very much a social experience. People like to hop in a game with their friends and either battle it out brawler style, join forces to destroy wave after wave of nazi zombies, or progress through a compelling story. But most people don't have a friend group always available right there in their living room, and so they take to the internet. There are many games that are single player, but it seems like the majority have some level of online cooperation or competition, which means somebody needs to build the netcode for all those games.

I have been spending the last few months working on the networking for a game, and learning about netcode in the process (from scratch, I knew basically nothing about it three months ago). In that time I have gone through quite a few resources trying to pick up tips, techniques, pitfalls, patterns, and architectural options to apply to my project. And I want to share those resources and some of the contained knowledge here. In the future I hope to write more posts about these different topics, this is an incredibly rich space that could still do with some more curation. From my own experience trying to learn all of this, there doesn't appear to be any single definitive place that has the breadth of information needed to begin implementing networking. But for now, a summary of existing resources feels like the right starting point

Game Networking Resources

Gaffer On Games

This guy is great. Back when I was learning more about game development as a teen, I was already enjoying reading this site. Now I have revisited his materials heavily over the last few months and reread most of the articles at least 2 or 3 times because they are so detail rich and contain a massive amount of information on the various approaches that can be taken towards netcode.

I would recommend starting with 'What Every Programmer Needs To Know About Game Networking'. It's been a commonly recommended article since it was published 10 years ago, and it does a great job of summarizing the history of game networking, some of the biggest challenges, and how those problems are being solved in a variety of different types of games today. After that read through the Networked Physics series for lots of great insights into how to deal with complicated systems over a network. In that series he covers a variety of different strategies for processing physics, handling input, dealing with latency and packet loss, and by the end of the series has an approach towards a complex simulation that performs well even under rather terrible circumstances. And finally, every post on his site is pretty great, so explore through and spend time on posts that seem interesting.

I would say my biggest issue with his stuff is that it can be a little bit tricky to figure out how to take the great ideas and more concretely incorporate them into an actual project. He doesn't go much into code architecture or cover those more low level nitty gritty details, and there isn't any full project source code available (or maybe there is for patreons?). This means, at least for me, going through the posts multiple times as I develop to get more insight into how to take the next step in development. But overall this is an incredible resource, and the lack of those specifics makes his site totally timeless, I suspect that in another 10 years his posts will continue to be some of the best out there.

Gabriel Gambetta

This is not nearly as jam packed of a resource as gafferongames, but it is nice that it walks through the whole process with some simple examples, and even provides a code sample at the end with a demo project. Gabriel also includes great diagrams that really help internalize exactly what is happening in each of the described situations. It's also a single series that goes from beginning to end, introducing concepts sequentially, which really helps building up the mental model and keeping everything very understandable the whole time.

One suggestion I have for this resource, consider actually building your own mini project as you work through this using the networking setup that you will be using for your larger project. The ideas are very concrete, and it shouldn't be that difficult to take each post and figure out how to implement some of the ideas as you go through. That makes this a great followup in some ways to the gafferongames material.

Tribes Networking Model

This is an incredibly in depth document describing exactly how the networking system in Tribes works. Obviously the details of any game are going to be specific to that game, but I took a lot of inspiration from the different layers of the networking system that they employed, and have incorporated a similar approach in my own project.

The core of the Tribes system is that the networking is broken out into three main layers: A platform packet module which handles actual sending and receiving of packets based on details of how the current OS/platform needs to do this, a connection manager to take care of directing outgoing packets to the right place and figuring out where incoming packets are coming from, and a stream manager that is in charge of actually taking packets and turning them into game behavior, and vice versa. There is a lot more juicy detail included in the paper, but that high level approach is something that made a lot of sense for me to incorporate in my project. It has made it much easier to have all the same code whether or not online multiplayer is enabled, and easily just swap out the packet module to avoid sending anything to the internet. It may not work for your situation, but it's an in-depth enough paper that there are likely to be concrete approaches and decisions that you can steal for your own work.

One thing I will say, it is very dense material. As with most of these resources, going through them over and over as your understanding of the space improves will be critical.

Source Multiplayer Networking

This resource gives a ton of insight into how Valve games like CS:GO approach networking. Starting with a brief summary of client-server terminology and networking, and moving into more complex topics such as entity interpolation, input prediction, and lag compensation. It doesn't dive super deep into any one of these, and the resources listed above are likely to have more in-depth information on specific topics, but I think as far as a 10-15 minute read to get information on the whole scope of a game, this is a great place to start!

I Shot you First: Networking the Gameplay of Halo Reach(video)

These next resources are all GDC talks. Being in the form of 1-2 hour videos they can be hard to skim for tidbits of information, but all of them have lots of great information so I would recommend sitting through them.

This one, originally given back in 2011, is about how Halo Reach handled networking. Obviously with a shooter like this there are a lot of tough decisions to be made about how to reconcile lagged decision making in a fast paced environment, and this talk goes over some of the strategies used by Bungie to resolve those decisions. This is a really beefy two hour talk, going over architectural decisions, netcode strategies, as well as measuring and optimizing network performance. There isn't much actual code, but there are tons of concrete details of how the game layers are structured, the responsibilities of each layer, how data is structured and prioritized, etc... It also gets into several specific examples, things like what happens when a grenade is thrown, activating equipment buffs, and dealing with resolving whether or not a player was shot. And even after all that there are numerous other techniques described, tools demonstrated, and strategies discussed for performance, optimizations, and reliability.

Overwatch Gameplay and Netcode (video)

Great GDC talk (from 2017) going over how Overwatch approaches gameplay and netcode. A large portion of this talk is actually barely about networking, and is instead about the more generic engine architecture that Overwatch is built upon. It uses a pretty complex seeming ECS (entity component system), and for a portion of the video they discuss some information about how that is structured and what types of components and systems it contains. But this groundwork is super important because the architecture dictates how they approach netcode. After that is in place the speaker gets into details about how they build networking into their systems, and structure data and game logic around a client-server architecture. Then there are a bunch of examples given, details discussed, and several challenges + strategies.

Many of the ideas in this talk are a little less general than in others. Because ECS systems are less common than a more traditional architecture many of the ideas won't be as applicable for a wide array of games, but there is still a fair bit of valuable information to be gleaned. And personally, I think for anyone that is building an ECS based game, this is probably one of the most valuable talks you could ever watch, for network programming or otherwise.

Similar: Overwatch Netcode Developer Talk (video)

This covers some of the same content as the previous resource, but at a higher and more abstract level, and doesn't go into nearly as much detail or breadth. Still a nice shorter and kinda fun video to watch for a succinct summary of how Overwatch works.

Physics of Rocket League (video)

This GDC talk from 2018 is a bit different from the others. Both of the other talks have lots of information about general gameplay issues and how to solve the sort of things that might come up in many different genres. This talk is different, Rocket League is a more complex physics simulation than most, so the problems they encounter are relatively focused around ensuring that physics simulation works well in a networked environment. There is some more general networking information, but a lot of the talk discusses ways to mess with physics to improve the experience, unique challenges with fast paced car physics, and other things like that. It's still a valuable talk, especially if you are working on a very physics based game, but if not it probably won't give quite as concrete of insight as the other talks.

Other Resources

Beej's Guide to Network Programming

Although not about game programming, this is widely considered one of the definitive resources on network programming. If you want more technical details on what sockets are and how to use them, details on ip addresses and other networking topics, as well as references and usage tips on various networking related system calls, along with a bunch of more advanced topics, this is the place to go! I haven't read through all of it, but I have referred to it a couple of times when wanting to understand a little bit more about the code that I'm writing.

16bpp C# Networking Tutorial

Since I'm developing a Unity game I have been doing all of my network programming using C# sockets. This tutorial series is the best one I have found for that. It covers a variety of different topics, but at the very least going through the UDP sections are likely to be very useful for anyone else writing netcode using UDP sockets.

This is a living post

I hope that this was a useful collection of resources for any of you getting started with game programming. I plan for this to be a living post, and I hope to add resources, improve upon the notes, and generally build this up more and more over time. As such, if you have any feedback or suggestions for resources I left out, send me a tweet (@aengusmcmillin) or an email (hello@aengusmcmillin.com). I will read every message and will definitely look at any resources sent my way.

Content Review Week 1

Sun, 16 Feb 2020 00:00:00 GMT

I consume a decent amount of content in a week, and I feel like I'm not getting as much value out of it as I could. In order to fix that I have been starting to take notes on nearly all of the non-entertainment content that I consume. I haven't been entirely successful with this, and there has been a book I binged and a couple of videos I ended up passively watching, but basically everything else in the last week or so I have been 'actively consuming', taking notes and summarizing ideas as I go.

I also decided I would use this exercise as practice hitting publish and to provide value to others, as such I'm putting this out into the world. Hope it proves useful to someone!

These aren't super polished notes, it is essentially a couple of bullet points for each piece of content. I hope to evolve this practice over time, but for now it's pretty rough.

Brené Brown on How to Navigate the Emotions You're Unwilling to Feel | The Tim Ferriss Show

Set of people that avoid certain emotions because they don't want to 'Open Pandora's Box'.
Ask them if they are living outside the box or if they are actually inside of it. It might be valuable to open it up!
We have all been through shit, and have built armor against those issues. Is that armor still helping us get through things? If not it is likely holding us back and hurting us.
The armor prevents people from growing, and prevents them from doing everything they can.
Question from the universe about what they will do about that armor
Two answers: either tell the universe screw you and tear it away, or ignore it and live with it, causing more pain
Can't pull off all the armor at once, need to take off parts of it and replace it with something else
Lots of internal, almost biological resistance to removing that armor, often need the help of a therapist to do so

Stacking the Bricks: How your 'Fuck This' moment changes everything

We make pronouncements and plans and fantasize about the future without doing anything but stewing in it
A bit of ourselves dies everytime we fail to do something we say we want to do
'Shoulds' are an attempt to beat ourselves into submission, and it doesn't work
Neither skill, experience, nor fame are reliable indicators of success
Lots of little tweaks that helped in Amy Hoy's class, but nothing totally did the trick
Many folks came back and succeeded after originally failing
The students who had success had had a 'Fuck This' moment (FTM)
If you haven't had an FTM, you can trigger one by having a bitchfest about everything you don't like about your life that can be changed
Avoid milquetoast feelings, have stronger feelings about changeable things instead
The iron of suckitude is already hot, unwrap the self protective bullshit surrounding it

Styling Android: Blog Ideation

Keep a pulse on things during my day to day work that might warrant a blog post
Even if someone else blogged about it, there is value in providing an alternate take
Keep tabs on events for new features and tools to write about
Avoid writing about a new thing if you can't provide more value, wait until you can
Browse the docs to discover things people may not be aware of, and then write about it and provide more than the docs do
Incorporate other interests (e.g. I have an interest in music, I should take advantage of that)
Sometimes there will be blind ideas. Make sure to recognize and capture them.
In terms of adding value, make sure not to closely rehash what the official docs have said, but don't search too much to try and find others that have covered similar topics. They will address it differently, and it's good to avoid being overly influenced.
Check for recent posts in aggregators (such as Android/Kotlin Weekly) to avoid immediately duplicating a topic
The process is a funnel, need to capture from a variety of sources and then filter down based on added value.

Styling Android: Blog Writing

Ideation is only the top of the funnel
Write the supporting code first. This helps frame the article, changes the perspective, and can filter out ideas that can't be accomplished
Consider setting up a private repo GitHub workflow to build the code privately and then publish it in a good way after it is ready.
Next stage is to write the article
Treat any form of writing as storytelling, even technical blog posts
Follow a good structure, begin by explaining the problem, spend the bulk of the post explaining what needs explaining, and end by summarizing the problem and what was done
Final stage is publishing. Make the post, publish to social media, and make the github repo public.

Ladybug Podcast on Personal Branding⁽¹⁾

Personal brand represents our core values
Personal brand is also a real and authentic, but tailored identity that is presented to the world
Consider incorporating branding into design systems, build your core values and the way you want to be perceived into your design system
A brand can help establish oneself as a domain expert, it can also work to separate your personal self from your professional
Building a brand builds an audience and can open up opportunities
Look at what others in the industry are doing for their branding. Emulate but don't copy those things, and make them your own
Major differences between social networks, and the audience from one won't necessarily follow you to others
Go the extra mile to differentiate yourself when starting out

Stacking the Bricks: Why blacksmiths are better at startups than you

Need to watch Mastercrafts show, apparently it encompasses almost all startup-founder flaws in one show
Wasting time on 'creative noodling' vs getting things done
Avoiding the repetition of the basics
Too much self importance
They don't have the patience to simply do the work over and over again to push through barriers and develop the craftsmanship
"It’s as if Galileo dropped his ball and feather from the top of the tower and, as they fell, sought to convince his audience by argument instead of simply looking."
Business in four sentences: ○ Don’t work on the basics every day? You’ll fail. ○ Don’t market constantly? You’ll fail. ○ Don’t solve your customer’s pains? You’ll fail. ○ Don't ship? Ha!
This post resonated with me, had similar experiences with my two day blacksmithing course but never really connected it to startups

Neil Gaiman Commencement Speech at the University of the Arts 2012

When you start out on a career in the arts, you have no idea what you're doing, and that's a good thing because you don't care about rules or possibilities
If you have an idea of what you want to make, or what you should do, just go and do that
Imagine where you want to be is a distant mountain. As long as you are going towards that mountain you are ok.
Learn to be thick skinned and deal with failure
Avoid doing anything purely for the money
Problems of success can be harder than those of failure because they aren't talked about as much
Imposter Syndrome - aka Fraud Police
We should be making mistakes
When things get tough make good art
Do the stuff that only you can do, live as only you can
"The moment you feel that just possibly you are walking down the street naked, exposing too much of your heart and your mind and what's on the inside, and showing too much of yourself. That's the moment you may be starting to get it right."
People get hired because somehow they get hired
Choose two of three: make good work, deliver it on time, make people like you
Enjoy the good parts, enjoy the ride
If you cannot be wise, pretend to be someone who is wise, and behave like they would

Juice it or Lose it, a gamedev talk

Games need to be 'juicy'
Often visual and audio 'juice', but not always
"Maximum output for minimum input"
Take advantage of tweening/easing for animations. Try different easing functions, tween different values (e.g. position, scale, rotation), and add randomness.
Sound is very important to 'juiciness', add impact effects, music, and generally give an audible response to lots of things
Add particles, effects, screenshake
Add personality to your game by giving character to things that otherwise wouldn't have any. Even just adding eyes to things can do a lot
Adding in these sort of elements can take something with really simple gameplay and make it feel like so much more

A sidebar on podcast notes I have started taking audio notes when I'm walking and listening to podcasts. I think this will prove to be the only way I can reliably take notes about content like this. I have something in the works to help with this that I will hopefully be able to put out more info about in the coming weeks.↩

Kotlin Part 2: Basic Syntax and First Project

Wed, 22 Jan 2020 00:00:00 GMT

Ok, so now that we have a working hello world program (yay!), today I want to go over the first proper project we will be building in this series, start covering the syntax of Kotlin, and using that syntax to make the first steps in the construction of that project.

Project #1: Text Adventure

To begin with we are going to be building a text adventure. The reason for this project is that it doesn't need to be super complicated, doesn't require any advanced features or require saving any state, just basic language features and some console IO, and it is fun and can be pretty much endlessly expanded if you find it interesting.

The one we will be building is going to be relatively basic, I don't intend to make a deep compelling game, but rather to build a small complete experience to demonstrate the topics needed without overly simplifying things.

Because I want to keep this small, I will be keeping this down to a pretty self contained adventure with an intro, only a couple of steps that can be done, and then a conclusion. The story pacing will be terrible, but it should give an idea of how to approach this sort of project should you choose to expand upon it or completely make up your own.

Here is a basic script for how a playthrough might look. At each of the decision points there will be different branches to build out, and we will introduce those as we build the project, but wanted to give an idea of what we will be building up front.

Welcome to Alanor. You have just arrived from Terra on the Gamma
6 shuttle. 

Immediately upon stepping out of the shuttle you notice that the air is thinner
than on Terra, and the gravity ever so slightly stronger. This will take some
getting used to.

In the shuttle station, along with a variety of other passengers arriving
with you or waiting for another shuttle, you see an *exit door*, a 
*vending machine*, and a *bathroom*. What do you want to do? 

$ Go to the vending machine

In the vending machine you see some very boring looking fare. There are *chips* ($20),
some sort of *candy* ($30), and *nutrient paste* ($50). Do you wish to get anything?

$ Nutrient paste

You scan your payment tag on the machine and out drops a pouch of paste. It is 
a gray color, slightly grainy, and tests slightly foul, but it is filling.

What do you want to do next? 

$ Head out the exit

You walk to the exit, open the door, and walk out into the light of the two
suns of Alanor. You are immediately met by someone you recognize as the recruiter
who hired you for the position out here.

You join them in their car, and head out for your new life on a new world.

GAME OVER

Do you wish to play again?

$ No
$

Obviously in any published game there would be more than a single room to explore, but for our purposes this should do the trick, and between the vending machine and bathroom there should be enough complexity to make modeling it interesting.

Hello World Syntax Basics

Now that we know what we are building we need to start figuring out how to build it! Since we already have a project ready in IntelliJ that isn't doing much we are just going to start with that program, remove the Hello World printing, and go from there. But first, let's take a look again at that code and discuss exactly what is going on:

fun main() {
    println("Hello World")
}

Although it is pretty basic, there are still a couple of key things being introduced.

First of all is function definitions. For those unfamiliar, functions are essentially an operation that can be performed. They can take in parameters, do some work, and might spit out a result. The fun main() { line is declaring a function called main that takes no parameters and doesn't return anything, but when called it can do work. The work done is wrapped in the curly brackets.

The second thing happening is a function call to println(). This call takes in a string and doesn't return anything, but what it does do is spit out the passed in string to the console. Given the nature of the text based adventure game we will be calling this function a lot.

And finally, the third thing to be aware of here is something a little bit less obvious, but the main function is a bit special. In Kotlin, a standalone function called main will be used as the entry point for a file. By entry point, I simply mean that when you run a file, as we did in the last lesson, the main function will automatically be called, and when it reaches the end the program will quit. Every program needs some sort of entry point, and although there are more complicated ways to set this up that we may address in the future, for now expect almost all of the projects we build to have a simple main function as the basis.

Now that you know what this all does, you can go ahead and delete the println line, leaving yourself with a nice empty main() method to start working in.

Looking at the project spec above, there is probably one unsolved issue that really stands out, and one that might be a bit more subtle. The obvious one: we need to be able to take user input, how do we do that? And the less obvious: we need to store state about what is happening! Let's address the second problem first because the answer to that is important to capturing user input. For now, we will be capturing state with something called Variables.

Let's start with the second problem because the solution is important to the first. The answer to storing state is in the use of Variables.

Variables

In programming, a variable is essentially a named thing that stores data. Depending on the programming language, these can behave differently and have different restrictions, but whatever language you are looking at, it will almost certainly have some type of variables.

In Kotlin, there are two types of variables available, either a mutable var, or an immutable val.⁽¹⁾ Kotlin is also a strongly typed language but with type inference, which, in plainer english, means that all variables have some type that the compiler knows about (not just determined at runtime), but that those types can be figured out by the compiler based on context and don't always need to be declared explicitly.

But to take a step back, now we are introducing the idea of types? Types are just that, the type of the data that is being represented. So an Int type is an integer number, a Boolean type represents a true/false value, a String type represents a string of text, etc... I won't get too deep into the details now, and we will revisit all of this later, but for now just know that that is what we are referring to when talking about types.

I suppose a couple of examples would probably help here. Here are a couple of code blocks demonstrating variables and types.

Oh yeah, one more thing first. Programming languages almost always support comments in the code that will be stripped out in compilation. Kotlin provides the double slash // , and everything after that is a comment. I will be using that a lot throughout this series in my code blocks to describe what is happening without breaking the code should you choose to test it in IntelliJ. Ok, back to the examples:

var testInt = 2 // Inferred to be an Int type
testInt = 5 // var is mutable and therefore can be changed


var testBool = true // Inferred to be a Boolean type
testBool = 5 // COMPILER ERROR! Can't assign an Int value to a Boolean type


val testString = "foo" // This is inferred to be a String type
testString = "bar" // COMPILER ERROR! val is immutable and can't be changed


val helloText = "Hello World"
println(helloText) // Same as our original, with the text pulled out to a variable

As you can see, the syntax is relatively straightforward, and hopefully those examples are understandable. That sort of basic syntax should cover ~80% of what you will need, and we will cover more advanced details as the series progresses.

Now that we know how to store state in variables, the next thing we need is to be able to capture user input so the user can make selections to progress through the game. To do this we will be introducing a new function: readLine

User Input with readLine

readLine is a function (same as println) that listens for user input on the console and returns whatever text was entered. Since function syntax may still be a bit unfamiliar, here are a few examples to help reinforce what has been covered:

val textEntered = readLine() // This will store whatever you enter in 'textEntered'

var mutableTextEntered = readLine()
// Do something with the text
mutableTextEntered = readLine() // Since mutableTextEntered is a var it can be overridden

We will be using that function, storing the results in a val, and for now simply printing the entered text and returning out of the game. Go ahead and paste or type this code block into your empty main() method, and run it.

println("Welcome to Alanor. You have just arrived from Terra on the Gamma 6 shuttle.")
println("")
println("Immediately upon stepping out of the shuttle you notice that the air is thinner")
println("than on Terra, and the gravity ever so slightly stronger. This will take some")
println("getting used to.")
println("")
println("In the shuttle station, along with a variety of other passengers arriving")
println("with you or waiting for another shuttle, you see an *exit door*, a")
println("*vending machine*, and a *bathroom*. What do you want to do?")

val selection = readLine() // IMPORTANT LINE: This will read in user input and store it
println("You selected: $selection")

You should see something like this in your IntelliJ output, with 'exit door' replaced by whatever you decide to enter.

Welcome to Alanor. You have just arrived from Terra on the Gamma 6 shuttle.

Immediately upon stepping out of the shuttle you notice that the air is thinner
than on Terra, and the gravity ever so slightly stronger. This will take some
getting used to.

In the shuttle station, along with a variety of other passengers arriving
with you or waiting for another shuttle, you see an *exit door*, a
*vending machine*, and a *bathroom*. What do you want to do?
**exit door**
You selected: exit door

Process finished with exit code 0

Hopefully at this point all of that code makes sense. It is basically just printing lines to spit out text setting the stage, reading in some input, and then printing that out. The only new thing here is the $selection syntax on the last line. Those are called String Templates. They are essentially a bit of code embedded in a string that gets evaluated and swapped in. So including $selection just replaces that with the contents of the selection val.

At this point this post is getting a bit verbose, and we have introduced a couple new concepts, so probably best to wrap it up here. But first, since this is a reasonable standalone addition to the project, we need to git committed.

Commit to Git

In order to stamp this change and keep it in your version control history you need to commit it to Git.

As demonstrated last time, committing is a two step process. First you stage all the changes with git add ., and then you commit with git commit -m "<SOME MESSAGE".

So do the same thing here, choosing a decent commit message so that you can have a good idea of what was done at this stage. Something along these lines:

$ git add .
$ git commit -m "Print intro and capture some user input. Kotlin Guide Part 2"

And you are good to go! If you ever want to look at your commit history, just enter git log and it will print out a list of your commits.

Next Time

In part 3 I want to start introducing more structure to the game. We need to be able to store more complicated state

A note on mutability
For those unfamiliar with the term, mutable simply means that the value can be changed, whereas immutable means that once the value has been set it can't later be changed.
Mutability is often necessary, but there are benefits to making something immutable as well. It can simplify the logic of your code and make it really easy to tell that once the value has been set you don't need to worry about it changing afterwards. So whenever possible it is usually advisable to make your code immutable.↩

Kotlin Part 1: Environment & Hello World

Tue, 14 Jan 2020 00:00:00 GMT

Before diving into the actual syntax and details of programming with Kotlin, first we need to get an environment setup and lay the groundwork. For this series I am going to be using a couple of different tools, and so we might as well get those all setup and configured now! This will be relatively Mac-centric because that is what I use, but I will try and provide links to alternative options for Windows users whenever possible.

IntelliJ

First up is the IDE we will be using for any and all non-android development. There are a couple of options out there (eclipse is the other big one), but personally I am partial to the IDEA suite of tools, so I will be using IntelliJ Community Edition for this series.

To get it setup, start by going to https://www.jetbrains.com/idea/download/ and downloading the Community version. Once that is done install it from the dmg or exe (depending on platform), and start it up. Assuming you don't have any settings to migrate over, continue with the 'Do not import settings' option, and follow the wizard to configure IntelliJ to fit your preferences. In case you want the same setup as me, the options I have selected are as follows:

UI Theme: Darcula
Launcher Script: Nothing configured
Default Plugins: Nothing changed
Featured Plugins: IdeaVim installed and enabled. Only enable this if you are familiar with vim!!!

Congrats, you have installed and configured your IDE!

Throughout this series I want to give tips and tricks on how best to take advantage of the tools, so expect occasional sidebars describing how to perform a refactor, or how to quickly create a new class, etc... Because I use Vim these might not always be the standard approach, but I will try to give the IdeaVim version as well as the standard version whenever possible.

Homebrew

Homebrew is basically a must have tool for developers on Mac. It is a package manager similar to apt-get or pacman on linux, and it allows you to easily install and manage a bunch of different utilities and apps on Mac. Whenever there is something that needs installing, my first approach is always to check Homebrew.

Installing Homebrew is super simple. Go to https://brew.sh/, copy the Install string, and paste that into your terminal. Follow the steps and you should be good to go!

Windows Alternative: There is a tool called Chocolatey that is a similar sort of package/app manager. I haven't used it extensively, and from what I understand it isn't nearly as good and well established as homebrew, but if you want to check it out, go to https://chocolatey.org/.

Git

Throughout this series I want to ensure that we are using at least some semblance of best practices from the get go, which definitely includes using Git. Throughout this series I will be trying to make regular commits, decent commit messages, and generally do a better job with version control than I normally do. If you are already a heavy version control user, you can probably disregard most of this and just do your thing, but I'm hoping to demonstrate a reasonably good workflow that will help all of us establish better version control habits.

Depending on your environment Git may already be installed. You can check this with the following:

$ git --version
git version 2.21.0 (Apple Git-122.2)

If a version is installed, you can skip the next steps if you want, although Apple tends to lag behind on the versions of software they ship, so it might be worthwhile to install your own copy anyway.

To install Git we will be taking advantage of the newly installed Homebrew! Simply go to your terminal, and enter:

$ brew install git
$ git --version
git version 2.24.1

If brew succeeds and the version is returned, you should be good to go.

At this point there is a little bit of configuration you will want to perform as well to make sure that things work properly. The next two commands will be to set your name and email address, so of course simply replace the ones listed with your own. This will set them globally for all repositories, and this information will be attached when you commit to identify yourself.

$ git config --global user.name "Aengus Finn"
$ git config --global user.email "me@aengusfinn.com"

Alternative Approach: If you are on Windows, or simply don't want to use Homebrew, you can go to https://git-scm.com/downloads and install it manually.

Project Setup

Now that we have a basic environment configured, it's time to get started coding. For this part we will just get a very basic Hello World project setup and running and committed to Git.

To begin with, select Create New Project in IntelliJ, select Kotlin in the sidebar, and then JVM | IDEA on the top of the list. Pick a name for the project (i'm going with Project1 for now), and a location for it (for this project ~/dev/teaching/kotlin/project1), and then finish.

Once the project has been created, expand the project in the sidebar, right click on the src folder, and create New→Kotlin File/Class, and name it main.kt. This will create an empty file that will be the entry point for this project.

Paste the following contents into the file, don't worry about what it does for now, I will get into the basics in the next part, for now we just need something to run.

fun main() {
    println("Hello World")
}

Once this has been pasted in, you should see a little green arrow to the left of the 'fun main()' line. Click on this and select Run 'MainKt'. A panel will open at the bottom, and you should see the words 'Hello World' print out.

Congratulations, you have built and run a Kotlin program!

Git Committed

Finally, it's time to get this committed to version control. This isn't a super complicated process, but there are a few steps to follow, especially when doing initial repo setup.

The first thing to take care of is creating a .gitignore file. For those unfamiliar with git, this file allows you to exclude files from being tracked. This is necessary for build output files, and other files that are generated either by the OS, the IDE, or by compilation.

Although you can create this file manually, and in many cases that will be the way to go, the easiest way to get started is probably just to go to gitignore.io, enter in a few tokens related to your project (in my case Kotlin, Intellij, and macOS), and copy the output into a file called .gitignore in the root of your project folder.

Once that is done you are ready to create the repository and commit this initial code. I won't go into the full details of how git works here, so for now just navigate in your terminal to your project folder and enter these commands and you will be done.

$ git init
$ git add .
$ git commit -m "Initial Commit"

Next Time

And with that you have a working environment and a Kotlin project built, running, and checked in to Git. Next time I will cover some basics of Kotlin syntax, introducing concepts in support of a project a bit more complex than Hello World. In support of that I will also go over the project, and discuss a development/git workflow we will be following. See you then!