From ae77f21474594fc4555bafa3291424b12ff3d4ac Mon Sep 17 00:00:00 2001
From: Rok Garbas <rok@garbas.si>
Date: Tue, 8 Dec 2020 11:59:23 +0100
Subject: [PATCH] Switch away from classification as Tier1-3

to classification to a more descriptive classification.
---
 doc/manual/src/contributing/cli-guideline.md | 44 ++++++++++++++------
 doc/manual/src/contributing/contributing.md  |  1 +
 doc/manual/src/contributing/hacking.md       |  1 +
 3 files changed, 33 insertions(+), 13 deletions(-)
 create mode 100644 doc/manual/src/contributing/hacking.md

diff --git a/doc/manual/src/contributing/cli-guideline.md b/doc/manual/src/contributing/cli-guideline.md
index 01df07136..0132867c8 100644
--- a/doc/manual/src/contributing/cli-guideline.md
+++ b/doc/manual/src/contributing/cli-guideline.md
@@ -58,12 +58,13 @@ them.
 
 This classification tries to separate commands in 3 categories in terms of
 their importance in regards to the new users. Users who are likely to be
-impacted the most by bad user experience. This does not mean that we will not
-take care of Tier3 commands, it means we will only put more helpful details for
-beginners into Tier1 commands.
+impacted the most by bad user experience.
+
+- **Main commands**
+
+  Commands used for our main use cases and most likely used by new users. We
+  expect attention to details, such as:
 
-- **Tier1**: Commands used for our main use cases and most likely used by new
-  users. From Tier1 commands we expect attention to details, such as:
     - Proper use of [colors](#colors), [emojis](#special-unicode-characters)
       and [aligning of text](#text-alignment).
     - [Autocomplete](#shell-completion) of options.
@@ -73,16 +74,32 @@ beginners into Tier1 commands.
       Nix ecosystem.
     - [Help pages](#help-is-essential) to be as good as we can write them
       pointing to external documentation and tutorials for more.
-- **Tier2**: Commands that are somewhere between Tier1 and Tier2, not really
-  exposing some implementation detail, but not something that we expect a user.
-  From Tier2 command we expect less attention to details, but still some:
+
+  Examples of such commands: `nix init`, `nix develop`, `nix build`, `nix run`,
+  ...
+
+- **Infrequently used commands**
+
+  From infrequently used commands we expect less attention to details, but
+  still some:
+
     - Proper use of [colors](#colors), [emojis](#special-unicode-characters)
       and [aligning of text](#text-alignment).
     - [Autocomplete](#shell-completion) of options.
-- **Tier3**: Commands that expose certain internal functionality of `nix`,
-  mostly used by other scripts.
+
+  Examples of such commands: `nix doctor`, `nix edit`, `nix eval`, ...
+
+- **Utility and scripting commands**
+
+  Commands that expose certain internal functionality of `nix`, mostly used by
+  other scripts.
+
     - [Autocomplete](#shell-completion) of options.
 
+  Examples of such commands: `nix store copy`, `nix hash base16`, `nix store
+  ping`, ...
+
+
 # Help is essential
 
 Help should be built into your command line so that new users can gradually
@@ -249,9 +266,10 @@ Here are few examples of flag `OPTIONS`:
 
 ## Prompt when input not provided
 
-For **Tier1** commands we want command to improve the discoverability of
-possible input. A new user will most likely not know which `ARGUMENTS` and
-`OPTIONS` are required or which values are possible for those options.
+For *main commands* (as [per classification](#classification)) we want command
+to improve the discoverability of possible input. A new user will most likely
+not know which `ARGUMENTS` and `OPTIONS` are required or which values are
+possible for those options.
 
 In cases, the user might not provide the input or they provide wrong input,
 rather then show the error, prompt a user with an option to find and select
diff --git a/doc/manual/src/contributing/contributing.md b/doc/manual/src/contributing/contributing.md
index e69de29bb..854139a31 100644
--- a/doc/manual/src/contributing/contributing.md
+++ b/doc/manual/src/contributing/contributing.md
@@ -0,0 +1 @@
+# Contributing
diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
new file mode 100644
index 000000000..2ad773dea
--- /dev/null
+++ b/doc/manual/src/contributing/hacking.md
@@ -0,0 +1 @@
+# Hacking