Requests for Discussion

1 Abstract

A Request for Discussion (RFD) is a version-controlled description of a process written in natural language. A process is any ordered list of actions which intends to achieve a defined goal. These actions are taken by humans working in systems.

This RFD describes the process of using RFDs at Simple and Fast, as well as why. In brief, the goal of RFDs is to disseminate knowledge about the processes which take place at Simple and Fast and how to improve them. To achieve this goal, this RFD introduces a process which:

1. Places all RFDs into a common repository.
2. Assigns each RFD a sequential number starting from RFD 1.
3. Populates each RFD with metadata fields: authors, labels, and state.
4. Enforces a standard first heading, Abstract, and last heading, References.

The guiding spirit of RFDs is that all that we do can be described in terms of processes. By thoughtfully thinking of what we do in this structured way, we abstract best practices, rulebooks, and such into constraints which do not limit creativity, but encourages it and allows us to constantly-iteratively improve.

2 When to use an RFD

An RFD should be created when:

1. Creating a new process.
2. Changing a committed process.

In these cases the RFD should specify the complete or changed process.

An RFD may also be created to describe some aspect of a process. This means that a RFD could be created to describe:

1. A common interface which couples internal systems to customers and thus forms an integral part of a process, specified in the form of a REST API.
2. A architectural or design decision which informed the development of a process.
3. Best practices which apply to many processes in common.
4. Ideas on how to improve processes.
5. Protocols which promote interoperability between processes.

3 The RFD process

3.1 Creating a RFD with metadata and state

A RFD must contain a header with this metadata:

---
title: Name of RFD
author: Author Name <author@simple.fast>
state: prediscussion
labels: onelabel, twolabel
---

The entirety of a RFD’s textual content must be written by a human.

The state field must contain one of the following six states:

1. ideation: a placeholder RFD with a narrowly-defined scope. Anyone may take this scope and begin work on it after changing it to prediscussion state.
2. prediscussion: work is being iterated on, but not yet ready for general discussion.
3. discussion: work is being discussed by interested parties as well as the original stakeholders.
4. published: a consensus has been reached, yet the RFD may still be discussed and updated.
5. committed: the RFD describes a widely adopted process or aspect thereof. Comments may be raised as issues, but changes should be proposed as a new RFD.
6. abandoned: a description of a process change which has been found to be non-viable and deliberately never implemented may be moved here to be archived.

The labels field may contain a comma separated list of labels from the following selection:

• process: description of a process or process change; not an aspect of a process
• corp: internal information or governance.
• hardware: self-explanatory
• software: self-explanatory

A RFD must contain the Abstract and References headings. The Abstract heading must provide a brief overview of the RFD. The References heading must provide a list of other RFDs and external citations if any were considered in the making of the RFD. RFDs may be linked to with a relative link directly while external citations should be cited using pandoc citation syntax.

3.2 Insights to include in RFDs

RFDs should include context and determinations under these two headers.

• Context is anything that explains why the description is the way it is. This might include viable options and the benefits and drawbacks of each option. It might also include reasoning with data and references so that our future selves may understand the decisions we’ve made. We should include business and customer considerations wherever relevant. Thse could be economic (relative cost and implications on the company over time, short-term and long-term); customer outcome based (impacts on customers versus alternatives); performance (visible to customers, regressions, and present benchmarks).
• Determinations describe decisions and committed direction based on the context.

3.3 The life-cycle of a RFD

1. A team member creates a RFD file of form <number>.md in the common repository under the docs directory using the next available number with initial state prediscussion or ideation. If prediscussion, all authors at this stage (recommended one main author, one seconder author) write their names and take ownership in driving the RFD forward; if ideation, author field is optional as a placeholder RFD. This is done in a separate branch of the common repository.
2. Once the initial authors think their work is ready for other contributors, they change the state to discussion and open a PR into the main repository. All interested parties are notified from watching the repository and are able to comment and review the RFD.
3. Based on the general consensus (and after no more than one month of discussion) the RFD either returns to prediscussion or changes to ideation or abandoned, or advances to the published state.
4. In published state, we continue to improve the RFD until widespread adoption takes place. Widespread adoption means that it is considered mature enough for teams to interoperate on or widely share the process, and most things have been considered. Once this happens, we advance to the committed state.
5. In the commited state, the RFD is considered adopted and complete. Continual improvement to our process will take place in a new RFD which should reference the committed RFD.

3.4 Key words used in a RFD

Sometimes a RFD will standardize requirements to make a process easy to follow. In this case, the following words will be used to indicate the level of a requirement in the same sentence.

1. must: The definition is an absolute requirement of the specification.
2. must not: The definition is absolutely prohibited by the specification.
3. should: There may be valid reasons to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course. In particular, for configuration, SHOULD values are the default unless explicitly changed.
4. should not: There may exist valid reasons to implement a particular behaviour, but the full implications of doing so should be understood and carefully weighed. In particular, for configuration, SHOULD NOT is the default behaviour unless explicitly changed.
5. may: An item is truly optional; implementations must interoperate with or without the included description.

4 Changing the RFD process

The best part about the RFD process is that it itself is expressed in this RFD! If you want to change the process, you can apply the RFD process to this RFD.

5 References