Skip to content

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

Closed
wants to merge 3 commits into from
Closed

Conversation

sacha-l
Copy link

@sacha-l sacha-l commented Nov 18, 2021

This PR does three things:

  1. Adds the folder structure for the "docs" section.
  2. Ports over all content from https://docs.substrate.io/v3/getting-started/installation and https://docs.substrate.io/v3/getting-started/windows-users/ to the docs/install page.
  3. Adds slugs in the frontmatter. I'm suggesting that for content in the "docs" folder, instead of having docs.substrate.io/docs/install for example, we just have docs.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. ⛴ 😃

Copy link
Contributor

@nuke-web3 nuke-web3 left a 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
Copy link
Contributor

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?

Copy link
Author

@sacha-l sacha-l Nov 18, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure.

Copy link
Contributor

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

@nuke-web3 nuke-web3 Nov 18, 2021

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

Copy link
Contributor

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

@nuke-web3 nuke-web3 Nov 18, 2021

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

Copy link
Contributor

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

Copy link
Contributor

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.

Copy link
Contributor

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
title: Substrate empowers developers
title: Substrate Empowers Developers

Page titles in title case?

Copy link
Author

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.

Copy link
Contributor

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?

Copy link
Contributor

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.

@nuke-web3
Copy link
Contributor

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.

Yeah I had some opinions here: #514
I separated out the various bits in there except the migration /tweaking of pages content. Happy to make a new PR if you generally agree with the flow that had introduced?

@sacha-l
Copy link
Author

sacha-l commented Nov 18, 2021

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.

Yeah I had some opinions here: #514 I separated out the various bits in there except the migration /tweaking of pages content. Happy to make a new PR if you generally agree with the flow that had introduced?

@nukemandan : All your suggestions seem valid to me. Why don't we merge this and you create a PR that focuses on this section?
For frontmatter stuff like keywords, I think it doesn't hurt to add them as you suggested. But it's also stuff that can more naturally be added once we fill up the pages with content. That's why I left them out for now.

@sacha-l sacha-l requested a review from nuke-web3 November 18, 2021 16:25
@lisa-parity
Copy link
Contributor

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

Copy link
Contributor

@lisa-parity lisa-parity left a 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.

@nuke-web3
Copy link
Contributor

nuke-web3 commented Nov 18, 2021

Migrating to polkadot-developers/docs-sandbox#1

@nuke-web3 nuke-web3 closed this Nov 18, 2021
@nuke-web3 nuke-web3 deleted the sl/sandbox-structure branch November 27, 2021 00:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants