Skip to content

Commit

Permalink
Starlight workshop (#201)
Browse files Browse the repository at this point in the history
* use builtin kbd for keyboard buttons

* add an always-draft starlight cheatsheet

* add more about steps and all

* Add section on using images and (barebones) section on workflow (still wip)

* Always mention geese

* Typo

* Add a Card for no good reason

* Add cta

* fix kbd html styling

* add writing materials

* more tweaks

---------

Co-authored-by: Brett Beutell <[email protected]>
  • Loading branch information
keturiosakys and brettimus authored Aug 28, 2024
1 parent 0d6eddf commit d794c3b
Show file tree
Hide file tree
Showing 7 changed files with 302 additions and 28 deletions.
20 changes: 0 additions & 20 deletions www/src/components/KeyboardButton.astro

This file was deleted.

5 changes: 2 additions & 3 deletions www/src/content/docs/docs/features/generating-with-ai.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@ import fpxGenAiSettingsBaseUrl from "@/assets/gen-ai-requests--settings-baseurl.
import fpxGenAiHostile from "@/assets/gen-ai-requests--hostile.png"

import Button from "@/components/Button.astro";
import KeyboardButton from "@/components/KeyboardButton.astro";
import { Tabs, TabItem } from '@astrojs/starlight/components';

Generating sample request data is a common and often tedious task in API development.
Expand All @@ -39,15 +38,15 @@ Let's say we have a route `POST /api/goose` that creates a new goose. This route
In the Fiberplane Studio UI, Studio's AI can generate these fields for us.
Once we've [enabled](#enabling-request-autofill) AI Request Autofill,
we can click the Magic Wand icon on the requests page to generate some request data.
(Feel free to also use the shortcut <KeyboardButton>cmd</KeyboardButton><KeyboardButton>g</KeyboardButton>.)
(Feel free to also use the shortcut <kbd>cmd</kbd><kbd>g</kbd>.)

In this case, Studio will generate a request body with the shape above.

<Image src={fpxGenAiGenerateBody} alt="Generated Request Body" />

Looks like we're going to create a goose named "Gus" who loves Golang. Very alliterative!

After this, we could go ahead and click <Button>Send</Button> (or press <KeyboardButton>cmd</KeyboardButton><KeyboardButton>enter</KeyboardButton>), and Studio will send the request to the API and create Gus.
After this, we could go ahead and click <Button>Send</Button> (or press <kbd>cmd</kbd><kbd>enter</kbd>), and Studio will send the request to the API and create Gus.

Under the hood, Studio keeps track of the most recent requests you've made to your API in order to generate request data that follows your current testing path.

Expand Down
5 changes: 2 additions & 3 deletions www/src/content/docs/docs/features/inspect-traces.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@ sidebar:
order: 2
---

import KeyboardButton from "@/components/KeyboardButton.astro";
import Button from "@/components/Button.astro";
import { LinkCard, Icon } from "@astrojs/starlight/components";

Expand All @@ -27,9 +26,9 @@ Select the request you want to see the trace for.

![Request detail view](@/assets/inspect-traces--request-details.png)

You can jump up or down the request overview using the <Button type="icon" style="secondary"><Icon name="up-caret" /></Button> and <Button type="icon" style="secondary"><Icon name="down-caret" /></Button> buttons at the top right of the page or simply pressing keys <KeyboardButton>j</KeyboardButton> and <KeyboardButton>k</KeyboardButton>.
You can jump up or down the request overview using the <Button type="icon" style="secondary"><Icon name="up-caret" /></Button> and <Button type="icon" style="secondary"><Icon name="down-caret" /></Button> buttons at the top right of the page or simply pressing keys <kbd>j</kbd> and <kbd>k</kbd>.

Hit <KeyboardButton>esc</KeyboardButton> to close the trace details view and return to the request list.
Hit <kbd>esc</kbd> to close the trace details view and return to the request list.

Alternatively, after you [make a request](/docs/features/making-requests) through Studio, you can click "Go to Trace Details" to see the trace for that request.

Expand Down
3 changes: 1 addition & 2 deletions www/src/content/docs/docs/features/making-requests.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@ import { Aside } from '@astrojs/starlight/components';
import { LinkCard } from '@astrojs/starlight/components';
import { Card } from '@astrojs/starlight/components';
import Button from '@/components/Button.astro';
import KeyboardButton from '@/components/KeyboardButton.astro';

import FirstRequest from '@/assets/making-requests--make-request.gif';
import CreateGoose from '@/assets/making-requests--create-goose.png';
Expand All @@ -32,7 +31,7 @@ Once you're up and running locally, the first page you see in Studio leaves you

When using Fiberplane Studio with the [Hono client library](/docs/components/client-library/), Studio automatically detects the routes in your Hono API and displays them in the sidebar.

In the example above, the first route, `GET /`, is selected by default. By clicking <Button style="primary">Send</Button>, we make a request to our API, and see the response in the panel below. (You can also hit <KeyboardButton>cmd</KeyboardButton><KeyboardButton>enter</KeyboardButton> to send the request.)
In the example above, the first route, `GET /`, is selected by default. By clicking <Button style="primary">Send</Button>, we make a request to our API, and see the response in the panel below. (You can also hit <kbd>cmd</kbd><kbd>enter</kbd> to send the request.)

If there were any logs along the way, we can see them in the "Debug" section.

Expand Down
275 changes: 275 additions & 0 deletions www/src/content/docs/docs/features/using-starlight.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,275 @@
---
title: Using Starlight
draft: true # don't change so it doesn't get published
sidebar:
order: 9999
---

import { FileTree, Aside, Steps, Card, LinkCard } from "@astrojs/starlight/components";
import Button from "@/components/Button.astro";

This is a little cheatsheet for using Starlight for documenting Fiberplane features on our website.


### Adding a new page

<Aside type="tip">

See if it fits under any existing docs pages - long docs pages are **good**. They are <kbd>cmd</kbd> / <kbd>ctrl</kbd><kbd>f</kbd>-able and allow the reader to find all info they need under one page.

</Aside>

To add another page, create a new file in the `src/content/docs/docs` folder.

<FileTree>
- astro.config.mjs
- package.json
- README.md
- ...
- public/ (e.g: file assets, plain text - not images!)
- src/
- assets/ images that need to be optimized by Astro
- components/ our custom reusable components
- pages/
- content/
- landing/
- blog/
- docs/
- docs/
- get-started.mdx
- components/
- client-library.mdx
- features/
- making-requests.mdx
- generating-with-ai.mdx
- **new-page.mdx**
- ...
</FileTree>

The Sidebar will be populated automatically. If not you can configure it in the `astro.config.mjs` file.

### How docs are organized

- Get started: just the quick start for now
- Components: an overview of each of the components
- Features: how to use main features of Fiberplane Studio (user flows)

### Frontmatter

Every document has a frontmatter section at the top that describes the most important elements. Some fields are mandatory and the site won't build if they are missing.

```md
---
title: Using Starlight # (required)
description: A short description of the page # page will build without this but you should include it
sidebar: # all optional but you might want to configure it sometimes
hidden: false # (optional) default is false you can hide it if you want
order: 5 # the order of the sidebar items (alphabetical otherwise
label: Getting started with Starlight # default is the title but you can change it

---


# My heading <!-- don't use h1s -->

My documentation page content

```

See full [frontmatter reference](https://starlight.astro.build/reference/frontmatter) for more information.

## Components

Starlight has a lot of components to organize your information. You can find the complete reference of what's builtin [here](https://starlight.astro.build/guides/components).

Builtin components can be imported from `@astrojs/starlight/components` and our custom ones from `@/components/*` directly in the same MDX file.

```mdx
import { Aside, Steps } from "@astrojs/starlight/components";
import { Button } from "@/components/Button.astro";
```

We'll highlight a few with some best practices.

### Using code components

Code components don't need to be imported, they can be added using the classic markdown syntax.

Provide as much context as possible:

- what is the environment? File or a shell? What is the file path?
- use appropriate syntax highlighting
- show the action using a diff or annotation

**This is good:**

```ts
import { Hono } from "hono";
import { instrument } from "@fiberplane/hono-otel";

const app = new Hono();

app.get("/", (c) => {
return c.text("Hello, world!");
});

app.get("/another-route", (c) => {
return c.text("Another route!");
});

export default instrument(app);
```

**This is better:**

```ts title="src/index.ts" ins={"Import the instrument function":2-3} ins={11-13} ins={"Wrapping the app with instrument":15-16}
import { Hono } from "hono";

import { instrument } from "@fiberplane/hono-otel";

const app = new Hono();

app.get("/", (c) => {
return c.text("Hello, world!");
});

app.get("/another-route", (c) => {
return c.text("Another route!");
});


export default instrument(app);
```

Full reference of the Expressive Code component can be found [here](https://expressive-code.com/key-features/syntax-highlighting/)

### Steps

Anytime you have multistep instructions, use the `<Steps>` component to render them as opposed to adding a list number in a heading.


<Steps>
1. Step 1

nested things here
2. Step 2

```sh
rm -rf /
```
3. #### Step 3 (can also be a heading)

</Steps>

### Aside

Use the `<Aside>` component to give tips or warnings about something.

<Aside type="caution">
<p>This is a caution!</p>
</Aside>

<Aside type="tip">
<p>This is a tip!</p>
</Aside>

<Aside type="danger">
<p>Don't do this!</p>
</Aside>

### Buttons and keyboard shortcuts

Instead of saying 'press the "Send" button' on the screen you can use the `<Button>` component to render a button with a nicer styling that resembles the buttons on the UI.

Press the <Button>Send</Button> button to send the request

```md
Press <Button>Send</Button> to send the request.
```

You can also use the HTML-native `<kbd>` component to render a keyboard shortcut.

Hit <kbd>cmd</kbd><kbd>enter</kbd> to send the request

```md
Hit <kbd>cmd</kbd><kbd>enter</kbd> to send the request.
```

Feel free to tweak the `Button.astro` component and color vars in the css files to match your needs.

### Adding images

<Aside type="caution" title="Avoid product screenshots when you can">
**Product** screenshots are great for demonstrating features, but they can become outdated quickly. Use screenshots sparingly.
</Aside>

To add an image to a page, first put it in the `src/assets` folder.

Then you can use standard markdown to add it to the page:

```mdx title="src/my-new-docs-page.md"
![alt text](@/assets/name-of-image.png)
```

You can also use the Astro Image component:

```mdx title="src/my-new-docs-page.mdx"
import { Image } from "astro:assets";
import fpxGenAiGenerateBody from "@/assets/gen-ai-requests--generate.gif"

<Image src={fpxGenAiGenerateBody} alt="Generate a request body with AI" />
```

***

If you're on a `mac` (_shoutout Tim 🍎_), use [CleanShot X](https://cleanshot.com/) to take screenshots.

If you don't feel like dealing with that, ask Brett, Lau, or Mies to take the screenshots for you.

A few things to keep in mind:

- Show as much of the UI as possible, don't zoom in on a specific part
- Use opacity to highlight or call out certain elements

<Aside type="tip" title="GIFs are large">
You can record gifs, but even when Astro optimizes them, they are still large files that a long time to load on the website.
</Aside>

We still haven't defined specific, consistent styles for images in our docs, so for now, use your best judgement on making screenshots look good.

## Workflow

Add documentation in the same branch as you're adding the feature.
You can comment out your pages if you don't want them to appear,
or use the `draft: true` frontmatter flag (like on this page) to hide it from the website in production.

<Card title="Website is published when we merge to main">
The website is deployed automatically when changes are merged into `main`.
Shoutout Lau. Shoutout GitHub Actions. Shoutout bash scripts.
</Card>

### Best practices

- Keep headings short and descriptive. They will appear automatically in the sidebar.
- See if you can append to a page as opposed to creating a new one. Long pages are good.
- Always mention Geese 🪿

### Writing guidance

Here are some materials from a technical writing course (shoutout Nele) we went through while back, for recap:

- [Slides for workshop 1](https://docs.google.com/presentation/d/1RB6XHTaqXOBayO-VNS2hfj3HFv16YlX2T-s_-0tQpgw/edit?resourcekey=0-FfJiVW7eBjC8rEfwhPumpg#slide=id.g5950a2689d_0_7)
- [Google technical writing materials 1](https://developers.google.com/tech-writing/one)
- [Slides for workshop 2](https://docs.google.com/presentation/d/19EHjrIg_rKkdTU2PAoY_QdpSkvUXhe5T4X23wvq7l1k/edit?usp=sharing&resourcekey=0-9NfSUt7iddOUiNoOQ_kKTw)
- [Google technical writing materials 2](https://developers.google.com/tech-writing/two)

Always feel free to enlist help for reviewing your writing!

## What Next

<LinkCard
title="Fix Some Docs"
href="https://fiberplane.com"
icon="external"
description="Peruse the docs website at fiberplane.com, and if you find a typo, bug, etc., open a PR to fix it"
/>
2 changes: 2 additions & 0 deletions www/src/content/docs/docs/features/webhooks.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
---
title: Test Webhooks
description: How to test webhooks in Fiberplane Studio
sidebar:
order: 4
---
import { Image } from "astro:assets";

Expand Down
20 changes: 20 additions & 0 deletions www/src/main.css
Original file line number Diff line number Diff line change
Expand Up @@ -124,3 +124,23 @@ h6 {
text-decoration: underline;
}
}


/* Styling buttons */

kbd:not(site-search kbd) {
background-color: var(--sl-color-gray-6);
border-radius: 0.25rem;
border: 1px solid var(--sl-color-gray-5);
box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
text-transform: uppercase;
display: inline;
font-family: sans-serif;
font-size: 0.6875rem;
font-weight: bold;
padding: 0.1rem 0.4rem;
margin: 0 0.25rem;
cursor: default;
line-height: 1;
transition: background-color 0.2s, box-shadow 0.2s;
}

0 comments on commit d794c3b

Please sign in to comment.