external links diataxis

nais · Jan 31, 2024 · bfd4f38 · bfd4f38
1 parent 3b44316
commit bfd4f38
Show file tree

Hide file tree

Showing 3 changed files with 12 additions and 16 deletions.
diff --git a/docs/technical/write-the-doc/markdown-guidelines.md b/docs/technical/write-the-doc/markdown-guidelines.md
@@ -0,0 +1,5 @@
+- notes  #TODO
+
+- highlights #TODO 
+
+- variables #TODO
diff --git a/docs/technical/write-the-doc.md → .../technical/write-the-doc/write-the-doc.md b/docs/technical/write-the-doc.md → .../technical/write-the-doc/write-the-doc.md
@@ -1,5 +1,3 @@
-
-TODO:Break into reference, and how-to + add content.
 ### NAIS Doc authoring guide
 
 This guide is a highly compressed summary of the doc theory published at [Diataxis](https://diataxis.fr/)
@@ -8,20 +6,13 @@ This guide is a highly compressed summary of the doc theory published at [Diatax
 
 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** 
+* [**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**
+* [**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**
+* [**Reference**](https://diataxis.fr/reference/)
     - Reference guides are technical descriptions of the machinery and how to operate it. Reference material is information-oriented.
-* **Explanation**
+* [**Explanation**](https://diataxis.fr/explanation/)
     - Explanation is a discusive treatment of a subject, that permits reflection. Explanation is understanding-oriented.
-
-
-## Markdown guidelines
-
-- notes  #TODO
-
-- highlights #TODO 
-
-- variables #TODO
+* [**Markdown guidelines**](./markdown-guidelines.md)
+    - "Style guide" that describes the Markdown conventions to be used when authoring NAIS-docs.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -61,6 +61,6 @@ nav:
     - Production ready?: technical/production-ready.md
     - Publications & Media: technical/publications-media.md
     - Installing nais: technical/installing-nais.md
-    - Write the doc: technical/write-the-doc.md
+    - Write the doc: technical/write-the-doc/write-the-doc.md
   - Social:
       - The Great Outdoors: social/the-great-outdoors.md