Put technical notes on the website. (#177)

Publish technical notes on the website.
jlewi · Aug 2, 2024 · f71718a · f71718a
1 parent 1f0b9fb
commit f71718a
Show file tree

Hide file tree

Showing 15 changed files with 113 additions and 58 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -2,9 +2,16 @@
 
 ## To Add A Banner At the Top Of A Page use
 
-
-```docsy
+```docsy {"id":"01J49N8FNVE9SFP3DPTM3F52A1"}
 {{% pageinfo %}}
 This is a placeholder page that shows you how to use this template site.
 {{% /pageinfo %}}
+```
+
+```sh {"id":"01J49N9KR89D85Z84YDEVAC563"}
+To run hugo locally
+```
+
+```sh {"id":"01J49NA03YRB6QCR5CGWN31V0K"}
+hugo serve -D
 ```
diff --git a/docs/content/en/docs/blog/_index.md b/docs/content/en/docs/blog/_index.md
@@ -1,6 +1,7 @@
 ---
 title: Blog
 menu: {main: {weight: 30}}
+weight: 30
 ---
 
 Blogs related to Foyle.
diff --git a/docs/content/en/docs/tech-notes/_index.md b/docs/content/en/docs/tech-notes/_index.md
@@ -0,0 +1,25 @@
+---
+description: Technical Notes About Foyle
+title: Tech Notes
+weight: 40
+---
+
+# Objective:
+**Describe**  how we want to use technical notes and establish guidelines on authoring technical notes (TNs) for consistency.
+
+# Why TechNotes?
+We use TNs communicate key ideas, topics, practices, and decisions for the project. TNs provide a historical record with minimal burden on the authors or readers. We will use TNs in Foyle to document our team engineering practices and technical “stakes-in-the-ground” in a “bite-sized” manner. Use a TN instead of email to communicate important/durable decisions or practices. Follow this up with an email notification to the team when the document is published.
+
+TNs are not meant to replace documents such as User Guides or Detailed Design documents. However, many aspects of such larger docs can be discussed and formalized using a TN to feed into the authoring of these larger docs.
+
+## Guidelines
+
+1. All TNs have a unique ID that TNxxx where xxx is a sequential number
+1. Keep TNs brief, clear and to the point.
+1. Primary author is listed as owner. Secondary authors are recognized as co-creators.
+1. Allow contributors to add themselves in the contributors section.
+1. TNs are considered immutable once they are published. They should be deprecated or superceded by new TNs. This provides a historical timeline and prevents guesswork on whether a TN is still relevant.
+1. Only mark a TN published when ready (and approved, if there is an approver).
+1. If a TN is deprecated mark it so.  If there is a newer version that supersedes it, put the new doc in the front matter.
+
+Happy Tech-Noting
diff --git a/tech_notes/architecture.svg → ...ntent/en/docs/tech-notes/architecture.svg b/tech_notes/architecture.svg → ...ntent/en/docs/tech-notes/architecture.svg
diff --git a/tech_notes/copilot_in_notebook.png → ...n/docs/tech-notes/copilot_in_notebook.png b/tech_notes/copilot_in_notebook.png → ...n/docs/tech-notes/copilot_in_notebook.png
diff --git a/tech_notes/runme_ulids.png → ...ontent/en/docs/tech-notes/runme_ulids.png b/tech_notes/runme_ulids.png → ...ontent/en/docs/tech-notes/runme_ulids.png
diff --git a/tech_notes/tn001_logging.md → ...ntent/en/docs/tech-notes/tn001_logging.md b/tech_notes/tn001_logging.md → ...ntent/en/docs/tech-notes/tn001_logging.md
@@ -1,7 +1,11 @@
-# Logging
+---
+title: TN001 Logging
+description: Design logging to support capturing human feedback.
+weight: 1
+author: "[Jeremy Lewi](https://lewi.us/about)"
+date: 2024-04-10
+---
 
-* **Author**: Jeremy Lewi
-* **Last Updated**: 2024-04-10
 * **Status**: Being Drafted
 
 ## Objective
@@ -13,16 +17,16 @@ Design logging to support capturing human feedback.
 One of the key goals of Foyle is to collect human feedback to improve the quality of the AI.
 The key interaction that we want to capture is as follows
 
-*. User asks the AI to generate one or more commands
-*. User edits those commands
-*. User executes those commands
+* User asks the AI to generate one or more commands
+* User edits those commands
+* User executes those commands
 
 In particular, we want to be able to link the commands that the AI generated to the commands that the user ultimately
 executes. We can do this as follows
 
-*. When the AI generates any blocks it attaches a unique block id to each block
-*. When the frontend makes a request to the backend, the request includes the block ids of the blocks
-*. The blockid can then be used as a join key to link what the AI produced with what a human ultimately executed
+* When the AI generates any blocks it attaches a unique block id to each block
+* When the frontend makes a request to the backend, the request includes the block ids of the blocks
+* The blockid can then be used as a join key to link what the AI produced with what a human ultimately executed
 
 ## Implementation
 

diff --git a/tech_notes/tn002_learning.md → ...tent/en/docs/tech-notes/tn002_learning.md b/tech_notes/tn002_learning.md → ...tent/en/docs/tech-notes/tn002_learning.md
@@ -1,8 +1,11 @@
-# Learning from human feedback
-
-* **Author**: Jeremy Lewi
-* **Last Updated**: 2024-04-23
-* **Status**: Publish
+---
+title: TN002 Learning from Human Feedback
+description: Allow Foyle to learn from human feedback.
+weight: 2
+author: "[Jeremy Lewi](https://lewi.us/about)"
+date: 2024-04-23
+status: published
+---
 
 ## Objective
 

diff --git a/tech_notes/tn003_learning_eval.md → ...en/docs/tech-notes/tn003_learning_eval.md b/tech_notes/tn003_learning_eval.md → ...en/docs/tech-notes/tn003_learning_eval.md
@@ -1,23 +1,20 @@
 ---
-runme:
-  id: 01HWP5TGX8T7WR6FDJNH0T5MAY
-  version: v3
+title: TN003 Learning Evaluation
+description: Measure the efficacy of the learning system.
+weight: 3
+author: "[Jeremy Lewi](https://lewi.us/about)"
+date: 2024-04-27
+status: published
 ---
 
-# Learning Evaluation
-
-* **Author**: Jeremy Lewi
-* **Last Updated**: 2024-04-27
-* **Status**: Published
-
 ## Objective
 
 Measure the efficacy of the learning system.
 
 ## TL;DR
 
 The key hypothesis of Foyle is that by using implicit human feedback, we can create an AI that automatically learns
-about your infrastructure. In [TN002_Learning](tn002_learning) and [PR#83](https://github.com/jlewi/foyle/pull/83)
+about your infrastructure. In [TN002_Learning](../tn002_learning/) and [PR#83](https://github.com/jlewi/foyle/pull/83)
 we implemented a very simple learning mechanism based on query dependent few shot prompting. The next step is to
 quantiatively evaluate the effectiveness of this system. We'd like to construct an evaluation data set that consists of
 queries whose answers depend on private knowledge of your infrastructure. We'd like to compare the performance of

diff --git a/tech_notes/tn004_runme.md → ...content/en/docs/tech-notes/tn004_runme.md b/tech_notes/tn004_runme.md → ...content/en/docs/tech-notes/tn004_runme.md
@@ -1,8 +1,11 @@
-# Integration With Runme.Dev
-
-* **Author**: Jeremy Lewi
-* **Last Updated**: 2024-05-07
-* **Status**: Published
+---
+title: TN004 Integration with Runme.Dev
+description: Integrate Foyle's AI capabilities with runme.dev.
+weight: 4
+author: "[Jeremy Lewi](https://lewi.us/about)"
+date: 2024-05-07
+status: published
+---
 
 ## Objective
 

diff --git a/..._notes/tn005_continuous_log_processing.md → ...-notes/tn005_continuous_log_processing.md b/..._notes/tn005_continuous_log_processing.md → ...-notes/tn005_continuous_log_processing.md
@@ -1,12 +1,15 @@
-# Continuous Log Processing
-
-* **Author**: Jeremy Lewi
-* **Last Updated**: 2024-05-31
-* **Status**: Published
+---
+title: TN005 Continuous Log Processing
+description: Continuously compute traces and block logs
+weight: 5
+author: "[Jeremy Lewi](https://lewi.us/about)"
+date: 2024-05-31
+status: published
+---
 
 ## Objective
 
-* Continuously compute traces and block logs
+Continuously compute traces and block logs
 
 ## TL;DR
 

diff --git a/tech_notes/tn006_continuous_learning.md → ...s/tech-notes/tn006_continuous_learning.md b/tech_notes/tn006_continuous_learning.md → ...s/tech-notes/tn006_continuous_learning.md
@@ -1,8 +1,11 @@
-# Continuous Learning
-
-* **Author**: Jeremy Lewi
-* **Last Updated**: 2024-06-07
-* **Status**: Published
+---
+title: TN006 Continuous Learning
+description: Continuously learn from the traces and block logs
+weight: 6
+author: "[Jeremy Lewi](https://lewi.us/about)"
+date: 2024-06-07
+status: published
+---
 
 ## Objective
 

diff --git a/tech_notes/tn007_shared_learning.md → .../docs/tech-notes/tn007_shared_learning.md b/tech_notes/tn007_shared_learning.md → .../docs/tech-notes/tn007_shared_learning.md
@@ -1,8 +1,11 @@
-# Continuous Learning
-
-* **Author**: Jeremy Lewi
-* **Last Updated**: 2024-06-19
-* **Status**: Being drafted
+---
+title: TN007 Shared Learning
+description: A solution for sharing learning between multiple users
+weight: 7
+author: "[Jeremy Lewi](https://lewi.us/about)"
+date: 2024-06-19
+status: published
+---
 
 ## Objective
 

diff --git a/tech_notes/tn008_auto_insert_cells.md → ...ocs/tech-notes/tn008_auto_insert_cells.md b/tech_notes/tn008_auto_insert_cells.md → ...ocs/tech-notes/tn008_auto_insert_cells.md
@@ -1,8 +1,11 @@
-# Automatically Inserting Suggested Cells
-
-* **Author**: Jeremy Lewi
-* **Last Updated**: 2024-06-30
-* **Status**: Published
+---
+title: TN008 Auto Insert Cells
+description: Automatically Inserting Suggested Cells
+weight: 8
+author: "[Jeremy Lewi](https://lewi.us/about)"
+date: 2024-06-30
+status: published
+---
 
 ## Objective
 

diff --git a/tech_notes/tn009_ai_notebooks.md → .../en/docs/tech-notes/tn009_ai_notebooks.md b/tech_notes/tn009_ai_notebooks.md → .../en/docs/tech-notes/tn009_ai_notebooks.md
@@ -1,8 +1,11 @@
-# Review AI in Notebooks
-
-* **Author**: Jeremy Lewi
-* **Last Updated**: 2024-07-05
-* **Status**: Published
+---
+title: TN009 Review AI in Notebooks
+description: Review AI in Notebooks
+weight: 9
+author: "[Jeremy Lewi](https://lewi.us/about)"
+date: 2024-07-05
+status: published
+---
 
 ## Objective
 
@@ -51,7 +54,7 @@ completer only autocompletes the current cell; it doesn't suggest new cells.
 
 ## Hex
 
-Hex magic lets you describe in natural language what you want to do and then it adds to the notebook to do that.
+Hex magic lets you describe in natural language what you want to do and then it adds the cells to the notebook to do that.
 For example, you can describe a graph you want and it will add an SQL cell to select the data
 [Demo Video](https://hex.tech/blog/magic-ai/).