Learning Journeys

Decision

We add Learning Journeys to the code base for important technical topics and expect everyone to read them.

Learning Journeys are marked with @learningJourney <name> <step>, e.g. @learningJourney Analytics 3 so that they can be easily found with search. They are listed in a central LEARNING_JOURNEYS.md file.

When someone changes code that is related to a learning journey, they double-check the full journey to ensure that it still makes sense.

In addition to the Learning Journey, it often makes sense to offer a short workshop or presentation on Learning Friday when a topic is introduced.

Problems

We have multiple different ways of writing code. Some can be standardized with linting, but some cannot. This makes it harder for developers to switch between different areas of the codebase.

When adding new technologies or structures, it can be hard to understand what they mean in practice without a concrete example.

Documentation outside the code base is hard to find and often overlooked.

Context

We use both Confluence and comments in code for documentation. Non-developers feel a bit comfortable, but also a bit intimidated by the code base. We codify architectural decisions inside our repository as ADRs.

We will grow to more teams in the future.

Options

Add Learning Journeys in the codebase
Add documentation in Confluence
Do not add documentation

Reasoning

At our current size, and with the expected growth in mind, we need a way to align, so no documentation is not an option. Documentation inside Confluence was not read that much, so putting it into code hopefully makes it more concrete and easier to find.

Consequences

How do we implement this change?

There are already a few Learning Journeys in the repo. The main implementation would be to remind everyone to check them out if they haven't yet, and to encourage writing new ones.

Who will implement the change?

The next team to write a Learning Journey could be either the Create team around how to write backend code, or the Collect team around CDK infrastructure.

How do we teach this change?

Learning journeys are hopefully self-explanatory.

What could go wrong?

We might not write Learning Journeys when needed, or they might get out-of-date.