Update guidelines according to new structure

Co-authored-by: Trong Huu Nguyen <trong.huu.nguyen@nav.no>

docs/technical/write-the-doc.md → docs/technical/doc-guidelines.md

@@ -1,4 +1,4 @@
-# Authoring the NAIS docs
+# NAIS documentation guidelines
 
 When writing [the documentation](https://github.com/nais/doc) we serve at [doc.nais.io](https://doc.nais.io) / `doc.<tenant>.cloud.nais.io`, we want to make sure that the content we provide helps our users to understand and use the platform we're making.
 
@@ -10,27 +10,56 @@ Some key points to keep in mind when writing the docs are:
 - [Consistency](#conventions) in style and tone
 - NAIS [Quality](https://diataxis.fr/quality/)
 
-## Diataxis ([https://diataxis.fr/](https://diataxis.fr/))
+## Structure
 
-_Diátaxis identifies four distinct needs, and four corresponding forms of documentation - tutorials, how-to guides, technical reference and explanation. It places them in a systematic relationship, and proposes that documentation should itself be organised around the structures of those needs._
+We structure our content primarily around what services NAIS provide, with some [honest exceptions](#honest-exceptions).
 
-To create contents you must determine what you are setting out to do. Are you writing a _Tutorial_, a _How-to guide_, a _Reference_ or is it a comprehensive _Explanantion_ of a concept.
+Under each service, or category of services, we use Diataxis with the following convention:
 
-### [**Tutorial**](https://diataxis.fr/tutorials/)
+The main page for a service is an _Explanation_ of the service. It should give a high-level overview of what the service is, why you would use it, and how it fits into the NAIS ecosystem.
 
-A tutorial is an experience that takes place under the guidance of a tutor. A tutorial is always learning-oriented.
+Example structure:
 
-### [**How-to**](https://diataxis.fr/how-to-guides/)
+```text
+some-service/
+├─ README.md # <- explanation
+├─ how-to/
+│  ├─ verb.md
+├─ reference/
+│  ├─ spec.md
+├─ .pages
+```
 
-How-to guides are directions that guide the reader through a problem or towards a result. How-to guides are goal-oriented.
+???+ note "Simple reference structure"
 
-### [**Reference**](https://diataxis.fr/reference/)
+    If the service contains a single reference page, and is likely to remain that way, you can skip the `reference` folder and place the reference page directly in the service folder as `reference.md`.
 
-Reference guides are technical descriptions of the machinery and how to operate it. Reference material is information-oriented.
 
-### [**Explanation**](https://diataxis.fr/explanation/)
+### Honest exceptions
 
-Explanation is a discusive treatment of a subject, that permits reflection. Explanation is understanding-oriented.
+- Top-level explanations
+- Top-level tutorials
+- Operate: Here we describe the tools and services that are used and required to operate the platform
+- Tags overview
+- Legal stuff
+
+### .pages file
+
+The `.pages` file is used to define overrides and customizations to the titles and order of the pages in the navigation menu. This is a feature of the [Awesome Pages plugin](https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/) for MkDocs.
+
+A conventional `.pages` file looks like this:
+
+```text
+title: My overridden title
+nav:
+- README.md
+- 💡 Explanations: explanations
+- 🎯 How-To: how-to
+- 📚 Reference: reference
+- application
+- job
+- ...
+```
 
 ## Conventions
 
@@ -55,33 +84,39 @@ For even more convenience, we have a `<<tenant_url("service")>>` function that w
 
 ### Code blocks
 
-We want to use expanded notes with the filename in the title and the code block inside the note. Preferably with syntax highlighting where applicable.
-This will give the reader a copy button with the relevant code and the filename will be visible in the navigation menu.
+When we use code blocks, set the correct language for syntax highlighting. Define a title and highlight lines if needed.
 
 ````markdown
-???+ note ".nais/app.yaml"
 
-    ```yaml hl_lines="6-8 11"
-    apiVersion: nais.io/v1alpha1
-    kind: Application
-    ...
-    ```
+```yaml title="describe content / filename" hl_lines="6-8 11"
+apiVersion: nais.io/v1alpha1
+kind: Application
+...
+```
 ````
 
 ### Alternate paths
 
 When the user is given a choice, we want to show both paths in the documentation. For example programming language, OS or different methods
 
 ```markdown
-  === "Linux"
-    linux specific stuff
-  === "macOS"
-    macOS specific stuff
+=== "Linux"
+
+  linux specific stuff
+
+=== "macOS"
+
+  macOS specific stuff
+
 ```
 
+!!! note "Indentation and blank lines"
+
+    Ensure you have tab indentation on the content block, as well as a blank line before and after.
+
 ### Links
 
-With the new structure links play a big part in the documentation. We want to make sure that the links are consistent and easy to understand. We use the following structure for links:
+We want to make sure that the links are consistent and easy to understand. We use the following structure for links:
 
 
 | Type of Link  | Icon                        | Link                                                       |
@@ -90,15 +125,15 @@ With the new structure links play a big part in the documentation. We want to ma
 | How-to guide  | :dart:                      | `[:dart: Learn how to ...](../)`                           |
 | Reference     | :books:                     | `[:books: Reference for ](../)`                         |
 | Tutorial      | :rocket:                    | `[:rocket: Tutorial for ...](../)`                         |
+| External link | :octicons-link-external-24: | `[:octicons-link-external-24: External link](https://...)` |
 | Prometheus    | :simple-prometheus:         | `[:simple-prometheus: Open Prometheus](../)`               |
 | Grafana       | :simple-grafana:            | `[:simple-grafana: Open Grafana](../)`                     |
-| External link | :octicons-link-external-24: | `[:octicons-link-external-24: External link](https://...)` |
 
 ### Tags
 
-We use tags to categorize and group the content.
-This allows for finding related pages by tag.
-Tags are written in the front matter of the markdown file:
+We use tags to categorize and group the content to make it easier to find, as an alternative to the navigation menu and search.
+
+Tags are written in the front matter of the markdown file like so:
 
 ```markdown
 ---
@@ -110,13 +145,42 @@ tags: [tag1, tag2]
 ...
 ```
 
-Tags should be in lowercase.
+#### Which tags should I use?
+
+We typically always tag the diataxis-type the page classifies as with these mappings:
 
-Tag the form of the page. The following tags are used:
 
 | Form         | Tag           |
 |--------------|---------------|
 | Explanation  | `explanation` |
-| How-to guide | `guide`       |
+| How-to guide | `how-to`      |
 | Reference    | `reference`   |
 | Tutorial     | `tutorial`    |
+
+Additionally we typically tag the page with the parent category. E.g. if you are writing a `How to`-guide under the 'metrics' category, you would tag it with `metrics` and `how-to`. We would then omit the `observability`-tag, as it would be very crowded. 
+
+We try to avoid having tags with only one page, as they are typically not so helpful. It also help to keep the Tags-overview page cleaner.
+
+
+## Diataxis ([https://diataxis.fr/](https://diataxis.fr/))
+
+_Diátaxis identifies four distinct needs, and four corresponding forms of documentation - tutorials, how-to guides, technical reference and explanation. It places them in a systematic relationship, and proposes that documentation should itself be organised around the structures of those needs._
+
+To create contents you must determine what you are setting out to do. Are you writing a _Tutorial_, a _How-to guide_, a _Reference_ or is it a comprehensive _Explanantion_ of a concept.
+
+### [**Tutorial**](https://diataxis.fr/tutorials/)
+
+A tutorial is an experience that takes place under the guidance of a tutor. A tutorial is always learning-oriented.
+
+### [**How-to**](https://diataxis.fr/how-to-guides/)
+
+How-to guides are directions that guide the reader through a problem or towards a result. How-to guides are goal-oriented.
+
+### [**Reference**](https://diataxis.fr/reference/)
+
+Reference guides are technical descriptions of the machinery and how to operate it. Reference material is information-oriented.
+
+### [**Explanation**](https://diataxis.fr/explanation/)
+
+Explanation is a discusive treatment of a subject, that permits reflection. Explanation is understanding-oriented.
+

flake.nix

@@ -0,0 +1,37 @@
+{
+  description = "dev env for handbook";
+
+  # Flake inputs
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs"; # also valid: "nixpkgs"
+  };
+
+  # Flake outputs
+  outputs = { self, nixpkgs }:
+    let
+      # Systems supported
+      allSystems = [
+        "x86_64-linux" # 64-bit Intel/AMD Linux
+        "aarch64-linux" # 64-bit ARM Linux
+        "x86_64-darwin" # 64-bit Intel macOS
+        "aarch64-darwin" # 64-bit ARM macOS
+      ];
+
+      # Helper to provide system-specific attributes
+      forAllSystems = f: nixpkgs.lib.genAttrs allSystems (system: f {
+        pkgs = import nixpkgs { inherit system; };
+      });
+    in
+    {
+      # Development environment output
+      devShells = forAllSystems ({ pkgs }: {
+        default =
+          pkgs.mkShell {
+            packages = with pkgs; [
+              python311
+              poetry
+            ];
+          };
+      });
+    };
+}