Redo documentation (#291)

Redo the information hierarchy to be more sensible * We had a lot of top level documentation (e.g. how to use Anthropic or Ollama) move this one layer deep into How Tos * This creates more consistent layout as now all pages are now at least one level deep in the hierarchy rather than being at the first layer Get rid of some sections * Reference there was no useful information in the FAQ so just delete * Use-Cases this only contained the email example. This example is no longer particularly relevant now that we are focusing more on operating on software. I also don't think the document does a good job of explaining/showing how to use Foyle. Its more about a specific CLI gctl.
jlewi · Oct 9, 2024 · 4189fe5 · 4189fe5
1 parent 627e7aa
commit 4189fe5
Show file tree

Hide file tree

Showing 31 changed files with 59 additions and 344 deletions.
diff --git a/README.md b/README.md
@@ -11,7 +11,7 @@ runme:
 Foyle is a copilot that works with VSCode Notebooks. As you describe your intent in a markup
 cell, Foyle suggests code cells containing commands you can run to achieve that intent.
 
-![Foyle Ghost Cells](images/foyle_ghost_cells.gif)
+![Foyle Ghost Cells](docs/static/images/foyle_ghost_cells.gif)
 
 Foyle is primarily intended to help software engineers operate their applications. Foyle simplifies
 software operations by removing the need to remember complex commands. Developers can just

diff --git a/docs/content/en/_index.md b/docs/content/en/_index.md
@@ -18,8 +18,10 @@ title: Foyle
 Foyle provides an AI powered assistant and literate environment to help you deploy and operate software.
 
 <div style="position: relative; padding-bottom: 25%; height: 0;">
-<iframe width="560" height="315" src="https://www.youtube.com/embed/_wbAW7CYluw?si=6sBN1L736XcKd5Qy" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
-</div>
+<video controls style="max-width: 50%; height: auto;">
+  <source src="https://storage.googleapis.com/foyle-public/videos/Foyle-Cost-Demo-Ghost-Cells-Part-1-with-captions.mp4" type="video/mp4">
+  <track src="https://storage.googleapis.com/foyle-public/videos/Foyle-Cost-Demo-Ghost-Cells-Part-1.vtt" kind="subtitles" srclang="en" label="English">
+</video>
 {{% /blocks/lead %}}
 
 

diff --git a/docs/content/en/docs/contributor/_index.md b/docs/content/en/docs/contributor/_index.md
diff --git a/docs/content/en/docs/developer-guide/_index.md b/docs/content/en/docs/developer-guide/_index.md
@@ -0,0 +1,7 @@
+---
+description: Documentation for contributors to Foyle
+title: Developer Guide
+weight: 20
+---
+
+This guide is for developers looking to contribute to Foyle.
diff --git a/...content/en/docs/contributor/assertions.md → ...ent/en/docs/developer-guide/assertions.md b/...content/en/docs/contributor/assertions.md → ...ent/en/docs/developer-guide/assertions.md
diff --git a/...en/docs/contribution-guidelines/_index.md → docs/content/en/docs/developer-guide/docs.md b/...en/docs/contribution-guidelines/_index.md → docs/content/en/docs/developer-guide/docs.md
@@ -1,5 +1,5 @@
 ---
-title: Contribution Guidelines
+title: Documentation Guidelines
 weight: 10
 description: How to contribute to the docs
 ---

diff --git a/docs/content/en/docs/contributor/eval.md → docs/content/en/docs/developer-guide/eval.md b/docs/content/en/docs/contributor/eval.md → docs/content/en/docs/developer-guide/eval.md
diff --git a/docs/content/en/docs/evaluation/_index.md b/docs/content/en/docs/evaluation/_index.md
diff --git a/docs/content/en/docs/getting-started/_index.md b/docs/content/en/docs/getting-started/_index.md
@@ -1,5 +1,5 @@
 ---
 description: Getting started with Foyle
 title: Getting Started
-weight: 1
+weight: 2
 ---
diff --git a/docs/content/en/docs/getting-started/k8s.md b/docs/content/en/docs/getting-started/k8s.md
@@ -4,9 +4,9 @@ title: Deploying Foyle on Kubernetes
 weight: 3
 ---
 
-{{< alert type="info" >}}
+{{% pageinfo %}}
 Deploying Foyle on Kubernetes is the recommended way for teams to have a shared instance that transfers knowledge across the organization.
-{{< /alert >}}
+{{% /pageinfo %}}
 
 
 ## Installation

diff --git a/docs/content/en/docs/getting-started/locally.md b/docs/content/en/docs/getting-started/locally.md
@@ -4,15 +4,19 @@ title: Getting Started Locally
 weight: 2
 ---
 
+{{% pageinfo %}}
+Deploying Foyle locally is the quickest, easiest way to try out Foyle.
+{{% /pageinfo %}}
+
 ## Installation
 
 ### Prerequisites: VSCode & RunMe 
 
-Foyle relies on [VSCode](https://code.visualstudio.com/) and [RunMe.dev](https://runme.dev/)
+Foyle relies on [VSCode](https://code.visualstudio.com/) and [Runme.dev](https://runme.dev/)
 to provide the frontend.
 
 1. If you don't have VSCode visit the [downloads page](https://code.visualstudio.com/) and install it
-1. Follow [RunMe.dev](https://docs.runme.dev/installation/installrunme#installing-runme-on-vs-code) instructions to install the RunMe.dev extension in vscode
+1. Follow [Runme.dev](https://docs.runme.dev/installation/installrunme#installing-runme-on-vs-code) instructions to install the RunMe.dev extension in vscode
 
 ### Install Foyle
 

diff --git a/docs/content/en/docs/how-tos/_index.md b/docs/content/en/docs/how-tos/_index.md
@@ -0,0 +1,5 @@
+---
+title: "How Tos"
+description: "Short how to guides for Foyle"
+weight: 3
+---
diff --git a/docs/content/en/docs/anthropic/_index.md → docs/content/en/docs/how-tos/anthropic.md b/docs/content/en/docs/anthropic/_index.md → docs/content/en/docs/how-tos/anthropic.md
@@ -1,7 +1,7 @@
 ---
-title: "Anthropic"
+title: "Use Anthropic"
 description: "Using Anthropic with Foyle"
-weight: 4
+weight: 2
 ---
 
 ## What You'll Learn

diff --git a/docs/content/en/docs/azure/_index.md → docs/content/en/docs/how-tos/azure.md b/docs/content/en/docs/azure/_index.md → docs/content/en/docs/how-tos/azure.md
@@ -1,5 +1,5 @@
 ---
-title: "Azure OpenAI"
+title: "Use Azure OpenAI"
 description: "Using Azure OpenAI with Foyle"
 weight: 3
 ---

diff --git a/.../content/en/docs/integrations/bigquery.md → docs/content/en/docs/how-tos/bigquery.md b/.../content/en/docs/integrations/bigquery.md → docs/content/en/docs/how-tos/bigquery.md
@@ -1,6 +1,6 @@
 ---
 title: "BigQuery"
-description: "BigQuery"
+description: "How to use Foyle to assist you with BigQuery."
 weight: 7
 ---
 

diff --git a/docs/content/en/docs/learning/configuring.md → docs/content/en/docs/how-tos/configuring.md b/docs/content/en/docs/learning/configuring.md → docs/content/en/docs/how-tos/configuring.md
@@ -1,5 +1,5 @@
 ---
-title: "Configuring"
+title: "Configuring RAG"
 description: "Configuring Learning In Foyle"
 weight: 1
 ---

diff --git a/...content/en/docs/integrations/honeycomb.md → docs/content/en/docs/how-tos/honeycomb.md b/...content/en/docs/integrations/honeycomb.md → docs/content/en/docs/how-tos/honeycomb.md
@@ -1,6 +1,6 @@
 ---
 title: "Honeycomb"
-description: "Honeycomb"
+description: "How to use Foyle to assist you with Honeycomb."
 weight: 8
 ---
 

diff --git a/docs/content/en/docs/ollama/_index.md → docs/content/en/docs/how-tos/ollama.md b/docs/content/en/docs/ollama/_index.md → docs/content/en/docs/how-tos/ollama.md
@@ -1,5 +1,5 @@
 ---
-title: "Ollama"
+title: "Use Ollama"
 description: "How to use Ollama with Foyle"
 weight: 3
 ---

diff --git a/docs/content/en/docs/integrations/_index.md b/docs/content/en/docs/integrations/_index.md
diff --git a/docs/content/en/docs/learning/_index.md b/docs/content/en/docs/learning/_index.md
diff --git a/docs/content/en/docs/operator-manual/_index.md b/docs/content/en/docs/operator-manual/_index.md
@@ -0,0 +1,7 @@
+---
+title: Operator Manual
+description: How to operate Foyle
+weight: 4
+---
+
+This guide covers operating and troubleshooting Foyle.
diff --git a/docs/content/en/docs/observability/ai.md → docs/content/en/docs/operator-manual/ai.md b/docs/content/en/docs/observability/ai.md → docs/content/en/docs/operator-manual/ai.md
diff --git a/docs/content/en/docs/observability/_index.md → .../en/docs/operator-manual/cloud-logging.md b/docs/content/en/docs/observability/_index.md → .../en/docs/operator-manual/cloud-logging.md
@@ -1,21 +1,12 @@
 ---
-title: "Observability"
-description: "Observability for Foyle"
+title: "Cloud Logging"
+description: "Use Google Cloud Logging for Foyle logs"
 weight: 7
 ---
 
 ## What You'll Learn
 
-How to use OpenTelemetry and Logging to monitor Foyle.
-
-## Configure Honeycomb
-
-To configure Foyle to use Honeycomb as a backend you just need to set the `telemetry.honeycomb.apiKeyFile` 
-configuration option to the path of a file containing your Honeycomb API key.
-
-```
-foyle config set telemetry.honeycomb.apiKeyFile = /path/to/apikey
-```
+How to use Google Cloud Logging to monitor Foyle.
 
 ## Google Cloud Logging
 

diff --git a/...ontent/en/docs/observability/honeycomb.md → ...tent/en/docs/operator-manual/honeycomb.md b/...ontent/en/docs/observability/honeycomb.md → ...tent/en/docs/operator-manual/honeycomb.md
@@ -1,6 +1,6 @@
 ---
 description: How to monitor Foyle with Honeycomb
-title: Monitoring Foyle With Honeycomb
+title: Honeycomb
 weight: 8
 ---
 

diff --git a/...en/docs/learning/troubleshoot_learning.md → .../operator-manual/troubleshoot_learning.md b/...en/docs/learning/troubleshoot_learning.md → .../operator-manual/troubleshoot_learning.md
diff --git a/docs/content/en/docs/overview/_index.md b/docs/content/en/docs/overview/_index.md
@@ -3,104 +3,32 @@ title: Overview
 weight: 1
 ---
 
-Foyle is a project aimed at building agents to help software developers
-deploy and operate software. 
-
-Foyle moves software operations out of the shell and into a literate
-environment. Using Foyle, users 
-
-* operate their infrastructure using VSCode Notebooks
-  * Foyle executes cells containing shell commands by using a simple API to execute them locally or remotely 
-    (e.g. in a container)  
-* get help from AI's (ChatGPT, Claude, Bard, etc...) which add cells to the notebook
-
-Using VSCode Notebooks makes it easy for Foyle to learn from human feedback and get smarter over time.
-
 ## What is Foyle?
 
-Foyle is a web application that runs locally. When you run Foyle you can open up a VSCode Notebook 
-in your browser. Using this notebook you can 
+Foyle is an AI assistant integrated with VS Code notebooks, through the [Runme extension](https://docs.runme.dev/). It helps you deploy and operate your application by letting you express your intent in natural language and then using AI
+to generate the commands to achieve that intent.
+
+![Foyle Ghost Cells](/images/foyle_ghost_cells.gif)
 
-* Ask Foyle to assist you by adding cells to the notebook that contain markdown or commands to execute
-* Execute the commands in the cells
-* Ask Foyle to figure out what to do next based on the output of previous commands
 
 ## Why use Foyle?
 
+* You struggle to remember complex commands and want to offload this problem to an AI
 * You are tired of copy/pasting commands from ChatGPT/Claude/Bard into your shell
-* You want to move operations into a literate environment so you can easily capture the reasoning behind the commands you are executing
-* You want to collect data to improve the AI's you are using to help you operate your infrastructure
-
-## Building Better Agents with Better Data
-
-The goal of foyle is to use this literate environment to collect two types of data
-with the aim of building better agents
-
-1. Human feedback on agent suggestions
-1. Human examples of reasoning traces
-
-### Human feedback
-
-We are all asking AI's (ChatGPT, Claude, Bard, etc...) to write commands to perform
-operations. These AI's often make mistakes. This is especially true when the correct answer depends on internal knowledge which the AI doesn't have.
-
-Consider a simple example, lets ask ChatGPT
-
-```
-What's the gcloud logging command to fetch the logs for the hydros manifest named hydros?
-```
-
-ChatGPT responds with
-
-```
-gcloud logging read "resource.labels.manifest_name='hydros' AND logName='projects/YOUR_PROJECT_ID/logs/hydros'"
-```
-
-This is wrong; ChatGPT even suspects its likely to be wrong because it doesn't have any knowledge of the logging scheme used by [hydros](https://github.com/jlewi/hydros).
-As users, we would most likely copy the command into our shell and iterate on it until we come up with the correct command; i.e
-
-```
-gcloud logging read 'jsonPayload."ManifestSync.Name"="hydros"'
-```
-
-This feedback is gold. We now have ground truth data `(prompt, human corrected answer)` that we could use to improve our AIs. Unfortunately, today's UX (copy and pasting into the shell)
-means we are throwing this data away.
-
-The goal of foyle's literate environment is to create a UX that allows us to easily capture
-
-1. The original prompt
-1. The AI provided answer
-1. Any corrections the user makes.
-
-Foyle aims to continuously use this data to retrain the AI so that it gets better the more you use it.
-
-### Reasoning Traces
-
-Everyone is excited about the ability to build agents that can reason and perform complex tasks e.g. [Devin](https://www.cognition-labs.com/introducing-devin).
-To build these agents we will need examples of reasoning traces that can be used to train the agent. This need is especially acute
-when it comes to building agents that can work with our private, internal systems.
-
-Even when we start with the same tools (Kubernetes, GitHub Actions, Docker, Vercel, etc...), we end up adding tooling on top of that.
-These can be simple scripts to encode things like naming conventions or they may be complex internal developer platforms. Either way,
-agents need to be trained to understand these platforms if we want them to operate software on our behalf.
-
-Literate environments (e.g. [Datadog Notebooks](https://docs.datadoghq.com/notebooks/)) are great for routine operations and troubleshooting.
-Using literate environments to operate infrastructure leads to a self documenting process that automatically captures
+* You value documentation and want to produce markdown documents that capture
+  1. The problem or question you are trying to solve
+  1. The commands you ran to solve the problem
+  1. The output of those commands
+  1. Your analysis and conclusions 
 
-1. Human thinking/analysis
-1. Commands/operations executed
-1. Command output
 
-Using literate environments provides a superior experience to copy/pasting commands and outputs into a GitHub issue/slack channel/Google Doc to
-create a record of what happened.
+## Who is Foyle for?
 
-More importantly, the documents produced by literate environments contain essential information for training agents to operate our infrastructure.
+If your building or operating software, Foyle can help you. If your an individual developer, you can deploy [Foyle locally](/docs/getting-started/locally). If you are a team, you can deploy Foyle on [Kubernetes](/docs/getting-started/kubernetes) so that you have a shared AI that spreads knowledge among the team.
 
-<!-- ## How you can help 
+## How much does Foyle cost?
 
-TODO(jeremy): We should ask people try it out but first we need it to be working enough 
-for people to try out.
--->
+Foyle itself is free to use. You will need to pay for your LLM usage by providing an API key or deploying your own LLM.
 
 ## Where should I go next?
 * [Getting Started](/docs/getting-started/): Get started with $project