-
Notifications
You must be signed in to change notification settings - Fork 284
Add placeholder docs structure #572
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
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Don't want to block this, but I think we should restructure just a bit:
@@ -0,0 +1,300 @@ | |||
--- | |||
title: Install |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I personally think this should be more on the lines of "Development Environment Configuration" - as "Install" is a bit of a misnomer for what you are doing. Did I miss where this was discussed and decided against?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sure.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I intend this section to cover more than dev env set up, please stick with Install for the section title
version: '3.0' | ||
section: docs | ||
category: developers | ||
keywords: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we seed all pages now with a handful of keywords that we think are core to each 1st level of the docs hierarchy? We can tweak latter on of course.
And if so, then copy these by default into higher level dirs and pages?
example here using the propper YAML syntax for items:
---
slug: /deploy
kewords:
- deployment
- devops
- launch
- CI
- CD
- .........
---
Another page in /deploy
:
---
slug: /deploy/cloud-hosting
kewords:
- deployment
- devops
- launch
- CI
- CD
- AWS
- GCS
- GCP
- .........
---
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
TO the extent possible, yes.
@@ -1,6 +1,6 @@ | |||
--- | |||
title: FAQ dropbox |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just FAQ, not FAQ Dropbox
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMHO this should be a sub-page of /reference
:
/reference/faq
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And this page should primarily point to the stack overflow once it's ready, and maybe a few fundamentally critical FAQ that we want to highlight from there.
I would propose a /referece/troublshooting
page as well that is a supplement outside the FAQ for common bugs and footguns with procedures how to fix them.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The idea for the drop box was a free-for-all--drop any markdown file in the folder and it will get listed as a link on this page.
Agree we should have troubleshooting, but it might be in multiple sections instead of being a standalone catch-all page.
@@ -1,6 +1,7 @@ | |||
--- | |||
title: Substrate empowers developers |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
title: Substrate empowers developers | |
title: Substrate Empowers Developers |
Page titles in title case?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Don't think so, no see: https://docs.substrate.io/v3/contribute/writing/#punctuation on capitalization.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
All heading levels should use the following conventions: Use sentence style case.
Headings are not Titles.... are they?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
All heading levels and titles should use sentence style case.
Yeah I had some opinions here: #514 |
@nukemandan : All your suggestions seem valid to me. Why don't we merge this and you create a PR that focuses on this section? |
@nukemandan Ideally, I'd like to see a simple outline of pages under the Install heading--if you are going to take on that section--before we go off on too many tangents. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We made a few small changes to the structure on Notion. Mostly, we are going to remove Migrate from the framework for now.
Migrating to polkadot-developers/docs-sandbox#1 |
This PR does three things:
docs/install
page.docs.substrate.io/docs/install
for example, we just havedocs.substrate.io/install
.cc @nukemandan : I know you had come up with a plan to organize the installation content: I thought I'd port over what we have and you can modify it from there. ⛴ 😃