Where should docs files live?

[Noviny]

Wanted to have a quick discussion on this so we know how to architect the website going forwards.

NOTE: docs for packages I think should live in the packages themselves. This is about system docs, primarily tutorials and guides (but also maybe

Current State:

Docs exist in a /docs directory. These are being mapped to the /guides section of the website.

My original intended future state

All docs files get moved into appropriate folders in the website (where a tutorials folder currently exists)

My new plan

This content will be way easier to navigate on github if it just continues to live in /docs, and the guides + tutorials folders are both sub-folders of that.

The website doesn't really care where it pulls info from, as long as the place it pulls from is consistent.

[jossmac]

I think something like this would be nice:

├── README.md          # can contain front-matter; pulled in by docz
├── LICENSE
├── package.json       # scope: `@keystone/*`
│
├── src/
│   ├── index.js       # only for exports
│   ├── ThingX.js
│   ├── ThingY.js
│   └── util.js
│
├── docs/              # when dynamic examples are needed; pulled in by docz
│   ├── thing1.mdx
│   └── thing2.mdx
│
└── docs.mdx           # maybe an entire directory is too much?

I guess the shape doesn't really matter; but I definitely have a preference for the docs to live with component/package/lib. Guides and tutorials can be wherever, probably /docs in root as mentioned by @Noviny.

[timleslie]

I'm +1 on having guides + tutorials under /docs and have the website as a separate concern which pulls these in as appropriate.

[Noviny]

@jossmac Pretty much agree with you in docs directory.

Currently experimenting with parsing .md files using the mdx parser, so things display nicely on github etc, so probably everything is .md, just some things contain mdx.