How to write a Principle

Quickstart - Writing your first principle

Note: If this is your first time creating a principle, use a combination of the Editor and this page to guide you. You can download a principle file from the editor by clicking the download link at the bottom of the page (once you've created a title and some content), to view the markdown file it generates.

There are only 3 things required for a principle:

Principle name
What it is
Why should you use it.

Meeting these requirements means it satisfies the requirements for a basic principle.

Aim to get your basic message across quickly. It helps give value straight away and is especially useful for those users who rely upon your principle as part of their decision-making process and want to refresh their memory.

It means explaining what it is and why you should use it in the first few paragraphs. There's no need to go in-depth at this point, as you can do that in later sections.

The principle can either be done under separate headers (e.g., https://principles.dev/p/compute-properties-when-possible/) or flow as a long-form article. As long as you explain the what, why very early on and integrate other parts of a principle somewhere in the text (e.g., references, how, content), it doesn't matter if you use separate headers or not. This may be useful if you've written your principle elsewhere and don't want to rewrite it to match this structure.

** Optional parts of a principle **

A basic principle is useful, but a full principle is even more so and contains other valuable but optional information.

How - can you implement it?
When - should you use it?
Article - General content. Open long-form text that can cover anything relevant.
Definitions of terms - Explanation of words that are unclear or overused.
Exceptions - When the principle might not apply
References - A list of contributing texts or links

How to upload a principle

Submit a pull request with your principle markdown file to Principles Github Repository for inclusion on the website. It's worth taking a look at the repository as it contains examples of the types of files you will need to create.

Principle content

Principle name

Should explain the principle as succinctly as possible.

Some examples:

Compute properties when possible
One single source of truth
Software must be easy to debug
Don't repeat yourself

What it is

One or more paragraphs that help explain the principle.

Example:

Don't repeat yourself (DRY, or sometimes do not repeat yourself) is a principle aimed at reducing repetition of software patterns, replacing it with abstractions or using data normalization to avoid redundancy.

NOTE: It is likely you will want to use parts of the "what it is" in the principle summary later

Why you should use it

A list, or paragraph, of one or more items that explain why the principle should be used.

How (optional)

A list, or paragraph, of one or more items that explain how the principle should be used.

Article (optional)

The article is the main body of the principle. It may be helpful to think of it as the sort of text you'd find in a blog post. It has two primary goals:

To convince the reader of why the principle is valuable to them.
To help the reader develop a deeper understanding

It could go into the history of the principle, what problems you may encounter during usage, examples in code, and many others.

You might find everything in the article that you would a typical blog post and contain every other item. e.g., the What, why, and how if written in free-form text.

For example, https://principles.dev/p/make-the-invisible-visible/ has some explicit headers, but due to the principle's nature (i.e., it is broader in scope), the article content is much greater. Whereas other principles forego it altogether https://principles.dev/p/ensure-documentation-is-easy-to-amend/

Definitions of terms (optional)

A list of words with overloaded or unclear meanings that need to be explained (e.g. a unit test, define what unit means, or what a model is in MVC). This can also be defined throughout the content.

Exceptions (optional)

A list of obvious cases or links to existing principles of when the principle would not apply. Which saves time having to create inverse principles to counteract undesired emergent behavior. For example: In "Compute properties when possible", an exception is: "Except in cases where performance is critical"

References (optional)

A list of resources used in defining this principle. Please ensure the resource has a permissible license if you have copied text from it.

Principle meta-data

The meta data, also known as the front matter, is a toml (https://toml.io/en/) formatted metadata section at the top of each principle. It used for generating important information for loading principles on to Principles.dev

+++
principle = "My Principle name"
tags = ["front-end", "back-end", "process", "team", "focused"]
summary = "The summary for my Princple"
authors = ["AdamCraven", "A Real Name"]
contributors = ["AnotherContributorUserName", "Another Real Name"]
license = "CC BY-SA 4.0"
allow_dual_licensing_to_GPLv3 = true
original_source = "http://example.com/previous-principle-url"
original_source_is_canonical = false
crystalized = false
uid = "<UUID4 goes here>"
+++

principle

principle = "My Principle Title"
# type = String

This is the principle title.

summary

summary = "principle summary which describes the principle"
# type = String

The summary is a short text that describes what the principle is in short form. It is visible as preview text on the website.

The summary should focus on what the principle is, rather than any other property of it (e.g. the advantage of using the principle). Users should be able to get a good understanding from the summary what the principle is and what it is about, especially because most principle titles are ambiguous.

authors

authors = ['AdamCraven', "User123", "Albert Einstein"]
# type = list/array of usernames or name strings

A comma-separated list of the original authors of the principle.

It can be your Principles.dev username if you want to link it to your account, or just your name if you do not want to connect it to your account or are not the original author. e.g. "AdamCraven" is a username, "Albert Einstein" is a name and won't link to an account.

The author is the person who would be considered the person who first wrote the principle.

If you are the original person who came up with this principle, you have the right to:

Choose the license for the principle.
Limit further changes.

If you took a generic principle that us considered too generic or is in the public domain, you have the right to:

Use the copyleft license CC BY-SA 4.0

But you cannot:

Prevent further changes to the principle
Claim authorship rights.

An example of a generic principle would be: https://principles.dev/p/one-single-source-of-truth/. It doesn't have an original author or was invented in several places independently. Therefore, it doesn't have any authors listed.

If you are not sure, it is best to avoid claiming authorship rights. Instead, put yourself down as the first contributor.

contributors

contributors = ['AdamCraven', "User123", "Albert Einstein"]
# type = list/array of usernames or name strings

A comma-separated list of the contributors to the principle.

If you make changes to a principle, you can put yourself down as a contributor. You cannot be both an author and a contributor to the same principle

license

license = "CC BY-SA 4.0"
# type = String of value: 
# "CC BY 4.0",
# "CC BY-SA 4.0",
# "CC BY-ND 4.0",
# "CC BY-NC 4.0",
# "CC BY-NC-SA 4.0",
# "CC BY-NC-ND 4.0",

The default license for content on the website is the Creative Commons Attribution ShareAlike 4.0 International [[CC BY-SA 4.0:https://creativecommons.org/licenses/by-sa/4.0/]].

The licensing choice is based upon the underlying principle of copyleft: that anyone can benefit freely from the previous work of others, but that any modifications to that work should benefit everyone else as well, and thus must be released under similar terms. ^{[https://en.wikipedia.org/wiki/Copyleft|[1]}

Can I chose another license?

Yes. There may be cases when you can want to license your principle differently. You can use any creative commons license: https://creativecommons.org/licenses/. However, if you chose any other creative commons license apart from CC BY-SA 4.0. it means that it cannot be dual-licensed (discussed below) to another source code-related license (e.g., MIT, Apache) as none are compatible (https://creativecommons.org/share-your-work/licensing-considerations/compatible-licenses).

Suppose you want to prevent others from editing your principle on this website but don't want to have a more restrictive license. You can crystalize your principle, which will prevent further edits to anything but housekeeping (e.g., fixing broken links, outdated terms, or spelling corrections).

allow_dual_licensing_to_GPLv3

allow_dual_licensing_to_GPLv3 = true
# type: boolean

If you use CC BY-SA 4.0 the principle is automatically dual-licensed under the compatible GPLv3 license. The dual-licensing enables programmers to pull the principles into a codebase and build future tooling software around it, such as tools to list a teams' principles or as a reference during code reviews, checked into the code base.

If you chose to use another license apart from CC BY-SA 4.0 or disable dual licensing. Then only the metadata will be distributed in packages.

** Will using the GPLv3 license mean all projects using any GPLv3 principles will have to release their source code under the same license? **

No. The GPL allows the use of software privately and commercially. As principles will not be distributed as part of the software and only used in tooling, it will not place any project restrictions.

** Our company has a blanket policy against GPL licenses; can I still use principles in our software stack? **

You will be able to use an MIT licensed version that contains only the information in the metadata (i.e., principle name, summary, tags) but without the main content.

original_source (advanced)

original_source = "https://principles.dev/p/the_original_source_url"
# type = string url

A link to the authors or originating source of the principle.

This should be used when:

The principle has been formally written out elsewhere e.g., the author's blog.
You want to derive another principle on princples.dev based on another principle on the website. e.g., original_source = "https://principles.dev/p/original_principle"

It should not be used:

as a replacement for general references
to link to Wikipedia

original_source_is_canonical (advanced)

original_source_is_canonical = false
# type: boolean

If principle content is identical or almost identical to the content on the original_source url, then a canonical meta tag (aka "rel canonical") will be applied on the Principles.dev website. The tag will tell search engines that original_source URL represents the primary copy of the page. This prevents problems with duplicate content and ensures that the original_source should appear higher in the search results.

This should be used when:

The content at the original_source is identical or almost identical to the principle and you want to avoid problems with duplicate content.

It must be used with:

crystalized - as uncrystallized principles may be edited.

crystalized (advanced)

crystalized = false
# type: boolean

Crystalization limits the principle, so only the original authors have permission to edit the principle. All without affecting the chosen license so others can still derive from it.

It is a message that the principle is in its final state and nothing further should be added to it.

Crystallization, in general, should be avoided. The community benefits from further contributions by adding additional content to the principle (e.g., more examples, references, etc...).

Even if crystalized, housekeeping edits will be permitted to fix broken links, change outdated terms, or fix spelling corrections. But the editors will not be listed as a contributor.

When to use:

When you want to restrict editing of a principle without choosing a more restrictive license.
When the principle is in a final state, and you do not wish further changes to be made.

uid

uid = "9c8fc618-b27..."

Used internally to keep track of principles, this will automatically generate when you download the principle from the editor https://principles.dev/create-a-principle/. If you are manually editing the file, you can use a generator here: https://www.uuidgenerator.net/version4.

Principle extra

filename

The filename of the principle that is uploaded to the github repository becomes the name of the URL on Principles.dev. e.g. compute-properties-when-possible.md will become /p/compute-properties-when-possible. Once created, the URL will not change, even if the title of the principle changes.

Media

Code examples

Code examples should be clear and understandable for most programmers. It doesn't have to work/compile.

JavaScript, Python, or other popular languages is the best choice for most code examples. But you can use any language if:

The examples are clear and straightforward (e.g., programmers will understand assignment and functions in most languages)
The principle is specific to that language (e.g., A principle about goroutines, memory allocation in Rust)
The principle is specific to that part of the stack (e.g., machine code, binary protocols)

Note: Don't rely on code examples as a crutch. The majority of your principle should be in the text as it shows understanding and communicates the message you intend to get across. Lots of code is likely to confuse the reader or require more time to decode your meaning. If you're getting close to 20 lines of code per example and your principle contains mostly code samples, it might not be the best approach.

Syntax

It should use generally available and understood language features. It should avoid bleeding edge or unknown features where a simpler feature would suffice.

Live Code

You can link to live code examples (e.g., https://jsfiddle.net, https://codepen.io/). The program must work.

Long-form code

For principles that require in-depth code examples, you can link to a gist, pastebin GitHub repositories, etc...

Highlighting

Code highlighting is supported for code blocks. To enable highlighting for a specific language, you will need to specify it on the opening part of the block after the three backticks.

e.g. ```python

Languages that are supported are shown here: https://pygments.org/languages/

Spelling

For consistency, all spelling should be in authors preferred vesion of English.

An example of differences:

British English: Behaviour, Aluminium
American English: Behavior, Aluminum

It is up to the original contributing author to use the spelling they would most prefer to use.

If you edit someone else's principle, use the version of English they have used throughout.

If you are unsure, use American English as a fallback.

Example of a principle file:

+++
principle = "Make the invisible, visible"
summary = "Make the hidden principles, ideas and behaviors which make up a technology organization understood and explicit"
tags = ["pde", "leadership", "epic"]
authors= ["AdamCraven"]
contributors = ["AnotherUser"]
license = "CC BY-SA 4.0"
allow_dual_licensing_to_GPLv3 = true
original_source="https://example.com/abc/"
original_source_is_canonical=false
crystalized=false
uid = "9c8fc618-b27..."
+++

Make the hidden principles, ideas and behaviors which make up a technology organization understood and explicit.

## Why

- Understanding is what allows an outcome to be reached. The greater the understanding the better the communication, efficiency and effectiveness of a team.

## How

- Use Principles combined with Principle-Driven Development to illuminate the technology organization from the source code to the leadership level.
- Ask questions that seek to understand and illuminate.

## Content

...