Write documentation guidelines

[sacha-l]

[WIP]
This is an issue to keep track of the items we want to address in our updated contribution guidelines for the new devhub launch.

Components

List all different components: Tip, Advice, Note, Warning, Important
Convention and examples of which instances to use them in
Docs, Tutorials, How-to guides

Full-stops after bullet-points. Convention tbd
TODO: Add link to the different guidelines (htgs, kb docs) here.

[sacha-l]

Add stuff about Message components:

You can use double quotes on the outside, and single quotes inside.

It's essentially mix/match syntax.

<Message
type={gray}
title={Note}
text={"Experienced developers may 'prefer' i've to skip that tutorial and install the Node Template according to the instructions in its readme."}
/>
<Message
type={gray}
title={Note}
text="Experienced developers may 'prefer' i've to skip that tutorial and install the Node Template according to the instructions in its readme."
/>
``

[sacha-l]

Also, for Components that use External links:

<Message
type={yellow}
title={Information}
text={[
'Learn more about ',
<ExternalLink
url={https://substrate.dev/rustdocs/v3.0.0/funty/trait.IsInteger.html#tymethod.wrapping_add}
>
wrapping_add
,
' and ',
<ExternalLink
url={https://substrate.dev/rustdocs/v3.0.0/frame_support/dispatch/trait.Encode.html#method.encode}
>
encode()
,
' in the Rust documentation.',
]}
/>

[sacha-l]

And for bulleted list:

<Message
type={green}
title={Further Learning}
text={`

• Safety. The mint function takes in an amount to 'mint' which is not good practice because it implies that
  users have unlimited access to writing to storage. Safer approaches include: using configuring 'GenesisConfig' or
  fixing a predetermined maximum value in runtime.
• Weights. All the weights were set to 10_000 in the above code snippets. Learn more about weight
  configuration in this basic guide on weights.
• Origins. One assumption this guide makes is that the origin will always be the sudo user.
  Origins are a powerful capability in Substrate. Learn more about how they work
  here.
  `}
  />

NOTE: code block backticks (e.g. on 'mint' and 'GenesisConfig' breaks the mdx.

[sacha-l]

On links / URLS: We are following a convention where no forward slash at the end of any link or url.

[sacha-l]

Adding Document Objectives in How-to Guides:

<Objectives
  data={[
    {
      title: 'Goal',
      description: 'Define a runtime constant value that becomes reset on `on_finalize`.',
    },
    {
      title: 'Use Cases',
      description:
        `Use a constant to keep track of the amount of times a function is called during a single block cycle.`,
    },
    {
      title: 'Overview',
      description:
        `Declaring a constant value in a runtime is a useful tool to either define fixed values or define values that change dynamically
         according to some factor. This guide steps through the process of creating pallet constants that are used to reset a \`u32\`
         value in storage. This value, we'll call \`SingleValue\`, can also be modified using a method called \`add_value\`.
         The purpose of this guide is to demonstrate the utilty of configuring constants by hardcoding them as well as making them more
         dynamic.`,
    },
  ]}
/>

Note: multi-line and back ticks / back slashes.

[sacha-l]

Note: move components examples and doc guidelines to separate folder.

[sacha-l]

We only use H2 ## Header and H3 ### Header to generate TableOfContents. As in those are the only anchor tags that will show up on the side-bar. Otherwise it crashes.

[jimmychu0807]

I suggest the following:

1. Abide to the 100 chars a line rule.
2. Avoid short form english, we'll -> we will.
3. Title should be capitalized, try this nifty tool.

@sacha-l what do you think?

[sacha-l]

I agree - I'm just not so sure about:

2. Avoid short form english, we'll -> we will.

Microsoft's guidelines actually encourage using contractions for the sake of having a more engaging and warm tone, which I sort of liked.

I think having @lsgunnlsgunn lean in here will be super helpful - she's currently helping with writing up these guidelines 😊

[sacha-l]

Add in stuff on Prettier here: #210

[sacha-l]

We should include a link to Substrate's contributing guidelines.

[nuke-web3]

<Message
type={gray}
title={Note}
text={"Experienced developers may 'prefer' i've to skip that tutorial and install the Node Template according to the instructions in > its readme."}
/>

So we want to enforce that the exact titles are preserved as we have in v3/docs/Examples/Components/index.mdx ?

I actually prefer that we can edit this to really make that title stand out. Here is an example:

If we don't want people to change (or have the ability to remove) the title, I would propose we make a new issue (phase-2 or latter) to remove this property and draw that from the type where that was not color, but of the selection note,info,warn,adv,future-reading,... and not have a user defined color.

a note: #231 (comment) fixes the code block rendering

Happy to go with whatever you think is best right now @sacha-l - just indicate yes/no here for custom titles for us 🙏

[lsgunnlsgunn]

I like the idea of customizable titles, but I would like to revisit the use of these components (when, where, and how to use them). Is this something a Ui / UC person recommended? If so, I’d like to involve him or her in the discussion post launch.

…

On Thu, Oct 7, 2021 at 10:43 AM Dan Shields ***@***.***> wrote: <Message type={gray} title={Note} text={"Experienced developers may 'prefer' i've to skip that tutorial and install the Node Template according to the instructions in > its readme."} /> So we want to *enforce* that the exact titles are preserved as we have in v3/docs/Examples/Components/index.mdx ? I actually prefer that we can edit this to really make that title stand out. Here is an example: [image: image] <https://user-images.githubusercontent.com/35669742/136435768-23932a88-5317-428b-b4bb-7d3efe7293de.png> If we don't want people to change (or have the ability to remove) the title, I would propose we make a new issue (phase-2 or latter) to remove this property and draw that from the type where that was not color, but of the selection note,info,warn,adv,future-reading,... and not have a user defined color. Happy to go with whatever you think is best right now @sacha-l <https://github.com/sacha-l> - just indicate yes/no here for custom titles for us 🙏 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#4 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AKRISG6YI5J5DV24XBCZS2LUFXL4FANCNFSM5BCSUV6A> .

[lsgunnlsgunn]

UI UX

…

On Thu, Oct 7, 2021 at 10:59 AM Lisa Gunn ***@***.***> wrote: I like the idea of customizable titles, but I would like to revisit the use of these components (when, where, and how to use them). Is this something a UI / UX person recommended? If so, I’d like to involve him or her in the discussion post launch. On Thu, Oct 7, 2021 at 10:43 AM Dan Shields ***@***.***> wrote: > <Message > type={gray} > title={Note} > text={"Experienced developers may 'prefer' i've to skip that tutorial and > install the Node Template according to the instructions in > its readme."} > /> > > So we want to *enforce* that the exact titles are preserved as we have > in v3/docs/Examples/Components/index.mdx ? > > I actually prefer that we can edit this to really make that title stand > out. Here is an example: > [image: image] > <https://user-images.githubusercontent.com/35669742/136435768-23932a88-5317-428b-b4bb-7d3efe7293de.png> > > If we don't want people to change (or have the ability to remove) the > title, I would propose we make a new issue (phase-2 or latter) to remove > this property and draw that from the type where that was not color, but > of the selection note,info,warn,adv,future-reading,... and not have a > user defined color. > > Happy to go with whatever you think is best right now @sacha-l > <https://github.com/sacha-l> - just indicate yes/no here for custom > titles for us 🙏 > > — > You are receiving this because you were mentioned. > Reply to this email directly, view it on GitHub > <#4 (comment)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AKRISG6YI5J5DV24XBCZS2LUFXL4FANCNFSM5BCSUV6A> > . >

[sacha-l]

💡 A note to include Substrate's contributing guidelines somehow. Maybe have a separate section referring to this doc for developers wanting to contribute to the codebase.

[sacha-l]

From Imad's recent PR: #449 (comment)

Steps to Contribute

Docs/HTGs (Adding new .mdx files)

• Create a New .mdx file(s) in the same folder tree
• Update DevNavMenu to reflect the addition of pages.

Tutorials (Adding new ones)

• Create a folder under /v3/tutorials/
• Create or place index.mdx inside the folder.
• Make sure to have ALL the following frontmatter defined

---
title: Create your first Substrate blockchain
slug: /tutorials/v3/create-your-first-substrate-chain
hideNav: true
sideNav: firstChain
version: '3.0'
section: tutorials
category: substrate chain
keywords: node template, basics
difficulty: 1
duration: 1 Hour
relevantSkills: 
  - Rust 
  - Blockchain basics
---

• Update DevNavMenu.tsx and add the menu items for tutorial. NOTE the name MUST match sideNav field in frontmatter.
  Gatsby will do the rest. No need to go into gatsby-config or gatsby-node file.
  🥳

[nuke-web3]

With #482 - we want to run yarn fmt:docs locally before making any final PR merge, and #500

[nuke-web3]

With Main-md branch launching, we will need to update and add this to the new content

[lisa-parity]

Closing this issue as obsolete (MDX-specific) and buried in the queue.
We do have a writing style guide:
https://www.notion.so/paritytechnologies/Using-this-guide-for-writing-and-style-581ffe4e80ea498d9fa0ffe4c00a753d
https://github.com/substrate-developer-hub/substrate-docs/tree/archive/main-mdx/v3/docs/00-style-and-contributor-guidelines/b-main-style-guide

We do have contributor's guidelines:
https://github.com/substrate-developer-hub/substrate-docs/tree/archive/main-mdx/v3/docs/00-style-and-contributor-guidelines/a-contributor-guidelines

They haven't been moved over and updated.
Pulled out of the archive and work in progress.
#1328