Skip to content

Commit

Permalink
Nais system documentation (#111)
Browse files Browse the repository at this point in the history
nais-system doc
  • Loading branch information
jhrv authored Oct 31, 2024
1 parent e2e01b0 commit 6cdbbc8
Show file tree
Hide file tree
Showing 9 changed files with 164 additions and 2 deletions.
3 changes: 3 additions & 0 deletions .envrc
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
if command -v nix-shell &>/dev/null; then
use flake
fi
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
.DS_Store
.idea
.idea
.direnv/
64 changes: 64 additions & 0 deletions docs/administrative/areas.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# NAIS areas

To ensure that all parts of NAIS are well taken care of, we have created what we call "areas". Everything we create, have a home in one of these areas.
Each area has one or two _anchors_. The anchors responsibility is to ensure that the area is well taken care of. They have oversight over the area, and are the go-to person for questions and discussions related to the area. E.g. if a [initiative](nais-system/initiatives.md) is proposed that affects the area, the anchor should be involved in the discussion.

NAIS is divided into several areas, each with its own anchor. The anchor is responsible for the area and is the go-to person for questions and discussions related to the area. The anchor is also responsible for keeping the area's board up to date.

## naisdevice
Ankere: Vegar og Torbjørn

## Persistence
**Anchor:** Morten

**Components:** DB, Kafka, Redis, OpenSearch, Bigquery, buckets

**Board**: https://github.com/orgs/nais/projects/23/views/1

## Deploy
**Anchor:** Kim Tore

**Components:** hookd, naiserator, liberator, deploy-action

## Auth
**Anchor:** Trong

**Components:** Digdirator, Azurerator, Wonderwall, TokenX, IAP / Forward Auth

**Board**: https://github.com/orgs/nais/projects/27/views/1

## Sårbarheter
**Ankere:** Tommy og Youssef

**Components:** SLSA, DependencyTrack, Picante, vulnerability scanning, Security Champion, supply chain security

## Observability
**Anchor:** Hans Kristian og Terje

**Components:** Prometheus, Grafana, Alertmanager, Loki, Tempo, Fluentd/fluentbit, node_exporter, kube-state-metrics, OpenTelemetry

## Cluster
**Anchor:** Sten

**Components:** Nais-terraform-modules, nettverk(mesh, lb, peering), k8s

## NAIS Tooling
**Anchor:** Thomas og Christer

**Components:** NAIS API, Console, NAIS CLI, Fasit

## NAIS meta
**Anchor:** Frode, Johnny

**Components:** doc, nais.io, handbook
---

**Misc:**
- KrakenD: Tommy og Sindre
- Unleash: Hans Kristian
- Gemini: Kim Tore
- Vault: Trong (https://github.com/orgs/nais/projects/26/views/1)




2 changes: 1 addition & 1 deletion docs/administrative/fixtures.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ The NAIS team might look disorganised to a newcomer and in a certain sense of th

![Froom logo](../assets/froom.png)

Thanks to COVID19 we have become "remote ~~first~~ only". And in case you are wondering; The froom is our zoom based digital workspace. Froom is a portmanteau of *Frode* and *Zoom*. Frode is a popular guy, so his personal Zoom space was where we all gravitated.
Thanks to a pandemic, we have become "remote ~~first~~ only". And in case you are wondering; The froom is our zoom based digital workspace. Froom is a portmanteau of *Frode* and *Zoom*. Frode is a popular guy, so his personal Zoom space was where we all gravitated.

We all hang out in the lobby and join breakout rooms for more in-depth exploration of topics that may not be of general interest.
Anyone is welcome anywhere but "good manners" apply.
Expand Down
24 changes: 24 additions & 0 deletions docs/administrative/nais-system/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# NAIS system

_NAIS system_ is the name of the process we use to develop NAIS.

The process a naisified version of [Shape Up from 37signals](https://basecamp.com/shapeup), and has been used since the beginning of 2024.

## A brief overview

We work in [cycles](cycle.md). Each cycle consists of a six week focus period where we split into smaller groups, usually 2-3 people, working on one or more [initiatives](initiative.md).

After each focus period we have a two week cool-down. Here we reset, re-orient and make plans for what's next.

Oh, and we also have [holiday-modes](holiday-mode.md) in the summer and around Christmas.

## Why do we organize our work this way?

- We value focus and deep work. We believe this leads to better solutions and happier team members. Having focus periods creates room for this.
- Basing our work on initiatives, forces us to be explicit and clear about our ideas. It makes it possible for everyone to keep up with what's happening and take part in the discussions. Bonus: a finished initative together with it's discussions serves as a ADR.
- When working on a initiative, you don't have to start each day wondering what to do. Also, you know that what you do, makes sense.
- We belive that it creates a healthy commitment towards the rest of the team: namely that during the alotted time, you try to focus and do your best work.
- Organizing our work this way, makes it possible to have a shared orientation in a large team.



9 changes: 9 additions & 0 deletions docs/administrative/nais-system/cycle.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# A NAIS cycle

## Focus period (6 weeks)
Every week during cooldown we have a [weekly](weekly.md)

## Cool-down (2 weeks)
- Tuesday in the first week in cooldown we have a [NAIS day](nais-day.md)
- Cut-off for initiatives is the last day of the first week in cooldown.
- Thursday in the second week we announce the first draft of the next focus period. Any adjustments to the draft must be made by the end of the week.
11 changes: 11 additions & 0 deletions docs/administrative/nais-system/holiday-mode.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Holiday modes

During the summer and around Christmas, we have what we call _holiday modes_.
These are week-long periods where we don't work in dedicated focus periods, but self-organize and let the work flow more organically. This is both because many people are on vacation, but also to break up the rythm a bit.

Some suggestions for what to do during holiday modes:

- Work on initiatives, or help out on the boards curated by the anchors. If you're unsure what to do, it can be a good idea to ask the anchor of the area you're interested in.
- Work on stuff you've put off during focus periods.
- Write a blog post.
- Check with your team if there's something you can help out with.
49 changes: 49 additions & 0 deletions docs/administrative/nais-system/initiatives.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Initiative

The scheduled work we do in our focus periods are described in what we call _initiatives_.

An initiative makes it clear _why_ this should be done, and _how_ it can solve _what_ for _who_.

The process of taking an idea to a proposed initiative, is typically referred to as _shaping_.

## Anatomy

These are the key components of an initiative:

### Essence

The essence should describe is the core idea and purpose of the initiative.
This should be clear and concise, and ensures that you have solid understanding of the problem.

In addition this helps the working group make scoping decisions along the way.

### Investment

All iniatives are timeboxed to a certain number of weeks or days. This is the upper limit of how much time we are willing to spend on it, before we do a re-evaluation.

It's important to note that this is not an estimate of how long it will take to complete the initiative, but rather a statement of how much time we feel is reasonable to spend on it given the potential impact.

### Non-goals

During the shaping process, you often identify rabbit holes and critial paths that you don't want to go down. These should be listed as non-goals with an explanation.

### Possible solution

Make sure that there actually exists a path to success by sketching out how one envisions an actual _possible_ solution.

This exercise ensures that what is proposed is technically feasible. By going through the moving parts involved, you're usually able to detect any obvious show stoppers as well as possible rabbit holes to avoid. These should be listed as [non-goals](#non-goals).

Having worked through this, we can see if we are introducing or removing any components, creating any new dependencies or taking on any new responsibilities.
Understand the technical and/or human impact is important aspects when evaluating the initiative.

If the solution impacts or involves some parts of Nais, make sure that the relevant people (e.g. anchors) are involved in the shaping process.

Rough sketches can also be helpful to help the working group understand the rough idea you have in mind.

Depending on how clear your understanding of the problem is, this can be a chaotic process where many ideas are thrown around and you find yourself exploring many alternative solutions, refining the essence, and the investment as you go along.
Note that the working group is free to deviate from this as long as the essence is preserved.


### Other relevant information

List any other relevant information that might be useful for the working group to know. Links, images, sketches, etc.
1 change: 1 addition & 0 deletions docs/administrative/nais-system/weekly.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
The NAIS weekly takes place Monday at high noon.

0 comments on commit 6cdbbc8

Please sign in to comment.