toastdotdev/toast

Documentation

Opened this issue · 6 comments

ChristopherBiscardi commented

There are no public docs at the moment. There are a few example sites around but we could make them more usable, discoverable, etc. Great documentation is a requirement before going GA. It is ok for the beta because we can help people in Discord, etc.

This issue needs to be broken down into more issues

maxcell commented

Things that would be worth documenting in one location:

  • Any important folder structuring or files worth noting? (src/pages/* + toast.js)
  • APIs (setDataForSlug)
  • Setting up a project with a starter
  • Troubleshooting (?)
    • This might not be necessary given that you've done work to embed how to get help within the errors themselves

Edit:

  • yarn create toast as a quickstart
maxcell commented

I think similar to https://mdxjs.org, it would be nifty to have a set of guides around the extra tooling you provide/patterns that emerge from the ecosystem.

If you wanted more folks to contribute to the rust side of toast I think there may be something separate you'd want (docs.rs for example) but also it could be some Architectural document potentially.

maxcell commented

If you wanted a set of sections written out, where would you be interested in having them? Maybe just a Markdown file as a PR to start and maybe another PR towards a more formal page in the www site?

ChristopherBiscardi commented

I've been thinking about this a bit lately.

The path forward is probably going to be put them in a root docs/ directory in toastdotdev/toast.

Then www.toast.dev will pull in the main branch and the latest release to render. This gives us documentation for every version (bread is released on merge), and also the releases (toast is released on changeset merge).

so the URLs on the toast site will be something like

toast.dev/docs/<version>/<files-in-docs>
toast.dev/docs/bread/files-in-docs

where version is either semver or a redirect from latest to the most recent release.

  • 👍1
  • 🎉1
ChristopherBiscardi commented

Seems like we end up with something like this for now

.
├── api
│   └── toastfile.mdx
├── api.mdx
├── getting-started
├── getting-started.mdx
├── guides
│   ├── beef.mdx
│   └── setting-up-mdx.mdx
├── guides.mdx
└── troubleshooting.mdx
ChristopherBiscardi commented

Guides: Adding client-side only functionality