Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Where should docs files live? #619

Closed
Noviny opened this issue Jan 15, 2019 · 3 comments
Closed

Where should docs files live? #619

Noviny opened this issue Jan 15, 2019 · 3 comments

Comments

@Noviny
Copy link
Member

@Noviny Noviny commented Jan 15, 2019

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
Copy link
Member

@jossmac jossmac commented Jan 15, 2019

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
Copy link
Contributor

@timleslie timleslie commented Jan 15, 2019

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

@Noviny
Copy link
Member Author

@Noviny Noviny commented Jan 15, 2019

@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.

@Noviny Noviny closed this Jan 18, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants