Skip to content

Commit

Permalink
added template files for each section -- explanation, tutorial, guide…
Browse files Browse the repository at this point in the history
… and reference
  • Loading branch information
akollegger committed Aug 27, 2024
1 parent d3f9303 commit 0e0038d
Show file tree
Hide file tree
Showing 14 changed files with 343 additions and 4 deletions.
22 changes: 19 additions & 3 deletions astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,22 @@ export default defineConfig({
},
sidebar: [
{
label: 'Guides',
label: 'Concepts',
items: [
{ label: 'Intro to GraphRAG', link: '/explanation/intro/' },
],
},
{
label: 'Tutorials',
items: [
// Each item here is one entry in the navigation menu.
{ label: 'Intro to GraphRAG', link: '/guides/intro/' },
{ label: 'Chat with a PDF', link: '/tutorials/chat-with-pdf/' },
],
},
{
label: 'How-to Guides',
items: [
{ label: 'Chunking', link: '/guides/chunking/' },
],
},
{
Expand All @@ -30,7 +42,11 @@ export default defineConfig({
autogenerate: { directory: 'reference/graphrag' },
},
{
label: 'Graph Patterns',
label: 'Data Preparation',
autogenerate: { directory: 'reference/preparation' },
},
{
label: 'Graph Shapes',
autogenerate: { directory: 'reference/knowledge-graph' },
}
]
Expand Down
86 changes: 86 additions & 0 deletions media/diagram-template.excalidraw
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
{
"type": "excalidraw",
"version": 2,
"source": "https://excalidraw.com",
"elements": [
{
"id": "3MMtvnlqtdgj1Cnckb_s-",
"type": "rectangle",
"x": 440,
"y": 255,
"width": 494,
"height": 200,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#a5d8ff",
"fillStyle": "hachure",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 2,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": "a0",
"roundness": {
"type": 3
},
"seed": 1812761710,
"version": 50,
"versionNonce": 1925151534,
"isDeleted": false,
"boundElements": [
{
"type": "text",
"id": "q_Og5WG56EY8BmiTtfJOO"
}
],
"updated": 1724761641841,
"link": null,
"locked": false
},
{
"id": "q_Og5WG56EY8BmiTtfJOO",
"type": "text",
"x": 598.6600036621094,
"y": 342.5,
"width": 176.67999267578125,
"height": 25,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#a5d8ff",
"fillStyle": "hachure",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 2,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": "a1",
"roundness": null,
"seed": 45417714,
"version": 21,
"versionNonce": 210700722,
"isDeleted": false,
"boundElements": null,
"updated": 1724761646797,
"link": null,
"locked": false,
"text": "Diagram goes here",
"fontSize": 20,
"fontFamily": 5,
"textAlign": "center",
"verticalAlign": "middle",
"containerId": "3MMtvnlqtdgj1Cnckb_s-",
"originalText": "Diagram goes here",
"autoResize": true,
"lineHeight": 1.25
}
],
"appState": {
"gridSize": 20,
"gridStep": 5,
"gridModeEnabled": false,
"viewBackgroundColor": "#ffffff"
},
"files": {}
}
13 changes: 13 additions & 0 deletions src/assets/images/diagram-template.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
10 changes: 10 additions & 0 deletions src/content/docs/explanation/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
title: Explanations
description: High-level concepts, independent of technical implementation or applied context
---

## Explanations

- [Intro to GraphRAG](/explanation/intro/) -
- [Knowledge Graph](/explanation/knowledge-graph/) -

10 changes: 10 additions & 0 deletions src/content/docs/explanation/intro.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
title: Intro to GraphRAG
description: RAG with a knowledge graph
---

![GraphRAG Overview](../../../assets/images/diagram-template.svg)

## Further reading

- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework
47 changes: 47 additions & 0 deletions src/content/docs/explanation/template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
title: (Explanation Template)
description: Make a copy of this to create a new explanation
---

<!-- Diagram -->

![GraphRAG Overview](../../../assets/images/diagram-template.svg)

**Instructions**:

1. Create a diagram using https://excalidraw.com
2. Save the Excalidraw file in `/media`
3. Save an SVG export of the diagram in `/src/assets/images`
4. Link to it above using a relative path

## About (Explanation)

**Instructions**:

1. Write a brief overview of at most 3 paragraphs, about the size of a LinkedIn post

An Explanation deepens and broadens the reader’s understanding of a subject. It brings clarity, light and context.

Explanation - understanding oriented, theoretical knowledge, that serves our study
The concept of reflection is important. Reflection occurs after something else, and depends on something else, yet at the same time brings something new - shines a new light - on the subject matter.

The perspective of explanation is higher and wider than that of the other not types. It does not take the user’s eye-level view, as in a how-to guide, or a close-up view of the machinery, like reference material. Its scope in each case is a topic - “an area of knowledge”, that somehow has to be bounded in a reasonable, meaningful way.

Explanations motivate why things are the way they are.

## Detailed (Explanation)

**Instructions**:

1. Add extra sections delving deeper into the topic

.

**Further reading**:

**Instructions**:

1. Provide links to external sources
2. Don't keep the link below, it's for your reference as the author

- Read [about explanations](https://diataxis.fr/explanation/) in the Diátaxis framework
11 changes: 11 additions & 0 deletions src/content/docs/guides/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
title: How-to Guides
description: A reference page in my new Starlight docs site.
---

A how-to guide helps the user get something done, correctly and safely; it guides the user’s action.

It’s concerned with work - navigating from one side to the other of a real-world problem-field.
## Further reading

- Read [about guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework
43 changes: 43 additions & 0 deletions src/content/docs/guides/template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
---
title: (How-to Template)
description: Make a copy of this to create a new how-to guide
---

<!-- Diagram -->

![GraphRAG Overview](../../../assets/images/diagram-template.svg)

**Instructions**:

1. Create a diagram using https://excalidraw.com
2. Save the Excalidraw file in `/media`
3. Save an SVG export of the diagram in `/src/assets/images`
4. Link to it above using a relative path

## About (How-to guide)

**Instructions**:

1. Write a brief overview of at most 3 paragraphs, about the size of a LinkedIn post

A how-to guide helps the user get something done, correctly and safely; it guides the user’s action.

It’s concerned with work - navigating from one side to the other of a real-world problem-field.

How-to guides describe how to do accomplish some goal.

## Detailed (How-to)

**Instructions**:

1. Add extra sections with step-by-step directions
2. Avoid implementation specific details (programming language or framework -specific)

**Further reading**:

**Instructions**:

1. Provide links to external sources
2. Don't keep the link below, it's for your reference as the author

- Read [about guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Example Reference
title: Reference Material
description: A reference page in my new Starlight docs site.
---

Expand Down
File renamed without changes.
42 changes: 42 additions & 0 deletions src/content/docs/reference/template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
title: (Reference Template)
description: Make a copy of this to create new reference material
---

<!-- Diagram -->

![GraphRAG Overview](../../../assets/images/diagram-template.svg)

**Instructions**:

1. Create a diagram using https://excalidraw.com
2. Save the Excalidraw file in `/media`
3. Save an SVG export of the diagram in `/src/assets/images`
4. Link to it above using a relative path

## About (Reference)

**Instructions**:

1. Write a brief overview of at most 3 paragraphs, about the size of a LinkedIn post

Reference material is ideal for outlining how things work in terse and clear terms.
Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you're documenting.

Reference material describes what something is.

## Detailed (How-to)

**Instructions**:

1. Add extra sections with step-by-step directions
2. Avoid implementation specific details (programming language or framework -specific)

**Further reading**:

**Instructions**:

1. Provide links to external sources
2. Don't keep the link below, it's for your reference as the author

- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework
File renamed without changes.
17 changes: 17 additions & 0 deletions src/content/docs/tutorials/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
---
title: GraphRAG Tutorials
description: A reference page in my new Starlight docs site.
---

## About Tutorials

A tutorial is a practical activity, in which the student learns by doing something meaningful, towards some achievable goal.

A tutorial serves the user’s acquisition of skills and knowledge - their study. Its purpose is not to help the user get something done, but to help them learn.

Tutorials - learning-oriented guides that describe practical steps and are intended to serve our study.
A tutorial in other words is a lesson.

*Further reading*:

- Read [about tutorials](https://diataxis.fr/tutorials/) in the Diátaxis framework
44 changes: 44 additions & 0 deletions src/content/docs/tutorials/template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
title: (Tutorial template)
description: Make a copy of this to create new tutorital
---

<!-- Diagram -->

![Tutorial diagram](../../../assets/images/diagram-template.svg)

**Instructions**:

1. Create a diagram using https://excalidraw.com
2. Save the Excalidraw file in `/media`
3. Save an SVG export of the diagram in `/src/assets/images`
4. Link to it above using a relative path

## About (Tutorial)

**Instructions**:

1. Write a brief overview of at most 3 paragraphs, about the size of a LinkedIn post

A tutorial is a practical activity, in which the student learns by doing something meaningful, towards some achievable goal.

A tutorial serves the user’s acquisition of skills and knowledge - their study. Its purpose is not to help the user get something done, but to help them learn.

Tutorials - learning-oriented guides that describe practical steps and are intended to serve our study.
A tutorial in other words is a lesson. They apply how-tos into a practical solution.

## Detailed (Tutorial)

**Instructions**:

1. Add extra sections that outline a complete solution

**Further reading**:

**Instructions**:

1. Provide links to external sources
2. Link to relevant how-tos and reference material used in the tutorial
3. Don't keep the link below, it's for your reference as the author

- Read [about tutorials](https://diataxis.fr/tutorials/) in the Diátaxis framework

0 comments on commit 0e0038d

Please sign in to comment.