Principle lists

[AdamCraven]

Lists are incredibly useful way of sharing principles and also for the success of principles.dev as a tool. Reality can be sliced in many ways and thus princples need to be flexible in their approach.

A common way of sharing principles is at the individual, team or organization level. But there are many more ways.

It can be shared via skill-set, by area of the code, by a component that has been created, by framework used, by structure of the code and many more.

Amongst that, when you share a list of princples, there is often context attached. Sharing principles is useful. But being able to add context, to add some cavaets, it will be more useful.

Designing the principle list.

The configurable principle list that exists on the website at the moment are a user's starred principles as seen here: https://principles.dev/u/AdamCraven/

These are principles that a user may want to show to the world or as a reminder of how they approach work.

At the moment it is basic.

There are 3 main functions of a prinicple list. Breaking these down into categories

Remind/Retrieve information - You know what the principles are, but you need to refresh that behavior. e.g. a code review
Inform - You don't know what principles are being used, but you need to learn them e.g. joining a new team, learning from a community leader, someone links to in a blog post.
Persuade - You don't know what principles are being used, you don't even know if you need them, but you may be persuaded e.g. team buy in, new architecture proposal.

Remind/Retrieve will be the most frequent use case on teams. It can be short and compact with additional annotations for that particular team.
Informing. May require mid-length information. As you need context for understanding. So more text fields
Persuade. will require much more space, but this is likely to happen outside of the website. In meetings, etc...

What exists already

https://monzo.com/blog/2018/06/29/engineering-principles

This a clear way of listing principles. It is titled engineering principles. It is a missing a lot of the "why" you would chose to employ these principles. The context at the start is useful.

https://principlesofchaos.org/

Concise with great context. It covers in a clear way principles that are most useful.

https://github.com/dwmkerr/hacker-laws

The principles listed here are easy to parse, but are uncategorized. They are general lists for guiding overal behaviour and increasing capability.

https://medium.com/bbc-design-engineering/moving-bbc-online-to-the-cloud-afdfb7c072ff

A list of higher level principles for justifying business decisions. Useful for team leadership, clear.

https://go-proverbs.github.io

A brief list of principles that can be revisited often. The titles are self-explainatory in this case, whereas many principles may need further context to understand.

https://overreacted.io/what-are-the-react-team-principles/

Very useful for understanding the behaviour and design decisions behind react.

http://rachelbythebay.com/w/2019/07/21/reliability/

Listed in a blog post form, not easy to parse.

https://principles.design/examples/

Long list of princples, often lacking context.

https://pubs.opengroup.org/architecture/togaf8-doc/arch/chap29.html

A long list of principles from the US Air Force. The principle name, what, why and how (to implement). The great thing about the US miltary is they have a lot of budget so documents like this are usually really well thought out

https://github.com/ukncsc/zero-trust-architecture/

I really like this one. It combines a lot of context up front with short summaries for each principle.

What's missing from the above

To build capability and habits, you need to be able to refresh yourself often. The one common problem with all the above principles lists are not in content, but context - The likelihood of revisiting them. The knowledge contained in them is incredibly valuable, but it is unlikely you'll remember them when you need them.

Goal

Create lists rapidly whilst having flexibility in how they are going to be used.

Designing a system

Synthesising from the above the most useful parts are:

Title - Name of the list
Context - When, it may be applicable. Why you might use it. Anything relevant to the use of it including history.
Principle titles
Principle what and why

Additional things that I think will be useful

Priority order of principles. Principles will overlap, ordering is going to be important.

To design lists there are a few options:

• Free-flowing text - The most basic, adaptable but least structured would be free flowing. Markdown format with some links to principles (urls). It could have an enchanced markdown format so when it sees special characters e.g. ">>" A dropdown link appears that allows you to search and add filters. Because of the free flowing nature of it, it would allow the most flexbility and could be the most useful. But with flexibility presents other problems. Namely lack of standardised approach and increased friction by not being able to create princple lists quickly.
• Partial free flowing text. You would be able to select principles and add notes underneath them for context. i.e. you may explicitly state why these are relevant principles to your particular projects. You might add caveats to the use of it. With freeflowing text for context at the top. This will allow a semi-structured approach, reduce friction as it's quick to select principles. But with reduced flexibilty for a result similar to free-flowing text.
• List title and principles. This is the most limited choice. You will have the title of the list e.g. "Adam's CTO list for use on project X" a list of princples. This will be the easiest to create for new users, but without context, it problem won't be that useful.

The design that fits best for the goal above is to create something simple, but have the ability to add some flexibility in how the principles are structured. Context is everything.

The solution

Looking at the variation of list types and use cases, I've realised I'm going to need to create at least 4 different list types.

1. The basic list. Listing of principles. Will appear on people's profiles.
2. The wider list. The priniciples in an expanded from that contain the summary and
3. The advanced list. Principles in extended form that can have advanced annotations and customisations
4. The multi-list. A grouping of of lists, to cover things like organisational principles or to focus the reader on one particular part.

I'll start with 1), but create a data model that is adaptable all the way to 4)

[AdamCraven]

Adding list types that have been identified:

• Technical management principles
• Organisational management
• Types of people e.g. Junior engineer, CTO, Data scientist to help
• Framework principles [object]
• Components e.g. implexas [object]
• Team lists
• Personal lists
• Code review lists [event/activity]
• Architecture list [object]
• Module list [object]
• Temporal list (different stages of a lifecycle) [phase]

[AdamCraven]

Taken from the user profile - a work in progress pic of the new lists feature.

[AdamCraven]

This feature is now live in its first form. It's available from your profile. It marks the first step in a much bigger goal towards better listing of principles

[AdamCraven]

Another list of principles, Stripes' culture https://stripe.com/en-gb/jobs/culture