From 9432c7141c6640763c1261bd3472a0ceeb73085b Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Tue, 8 Nov 2022 22:14:05 +0100 Subject: [PATCH 1/5] add docs guidelines --- docs/DOCS_GUIDELINES.MD | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 docs/DOCS_GUIDELINES.MD diff --git a/docs/DOCS_GUIDELINES.MD b/docs/DOCS_GUIDELINES.MD new file mode 100644 index 00000000000..f4bff7b0266 --- /dev/null +++ b/docs/DOCS_GUIDELINES.MD @@ -0,0 +1,40 @@ +# Documentation guidelines + +## Best practices + +- Check the spelling and grammar, even if you have to copy and paste from an external source. +- Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share. +- Try to express your thoughts in a concise and clean way. +- Use `-` between the acronyms ADR and ICS and the corresponding number. +- Don't abuse `code` format when writing in plain English. +- Follow Google developer documentation [style guide](https://developers.google.com/style). +- Check the meaning of words in Microsoft's [A-Z word list and term collections](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms) (use the search input!). +- We recommend using RFC keywords in user documentation (lowercase). The RFC keywords are: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). + +### Links + +**NOTE:** Strongly consider the existing links - both within this directory and to the website docs - when moving or deleting files. + +Relative links should be used nearly everywhere, due to versioning. Note that in case of page reshuffling, you must update all links references. + +### Code snippets + +Code snippets can be included in the documentation using normal Markdown code blocks. For example: + +```md + ```go + func() {} + ``` +``` + +It is also possible to include code snippets from GitHub files by referencing the files directly (and the line numbers if needed). For example: + +```md + ```go reference + https://github.com/cosmos/ibc-go/blob/v5.0.0/modules/core/04-channel/keeper/handshake.go#L18-L65 + ``` +``` + +## Technical writing course + +Google provides a free [course](https://developers.google.com/tech-writing/overview) for technical writing. \ No newline at end of file From cd0e5822b86a654d9ace146ac399dfa8dba4e2de Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Wed, 9 Nov 2022 11:02:34 +0100 Subject: [PATCH 2/5] Update DOCS_GUIDELINES.MD --- docs/DOCS_GUIDELINES.MD | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/DOCS_GUIDELINES.MD b/docs/DOCS_GUIDELINES.MD index f4bff7b0266..1656fd9c62a 100644 --- a/docs/DOCS_GUIDELINES.MD +++ b/docs/DOCS_GUIDELINES.MD @@ -5,7 +5,7 @@ - Check the spelling and grammar, even if you have to copy and paste from an external source. - Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share. - Try to express your thoughts in a concise and clean way. -- Use `-` between the acronyms ADR and ICS and the corresponding number. +- Leave a space between the acronyms ADR and ICS and the corresponding number (e.g. ADR 008 or ICS 27). - Don't abuse `code` format when writing in plain English. - Follow Google developer documentation [style guide](https://developers.google.com/style). - Check the meaning of words in Microsoft's [A-Z word list and term collections](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms) (use the search input!). @@ -37,4 +37,4 @@ It is also possible to include code snippets from GitHub files by referencing th ## Technical writing course -Google provides a free [course](https://developers.google.com/tech-writing/overview) for technical writing. \ No newline at end of file +Google provides a free [course](https://developers.google.com/tech-writing/overview) for technical writing. From af3828572b6cb977509922e0bdbfacefb50e99f4 Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Wed, 9 Nov 2022 11:02:50 +0100 Subject: [PATCH 3/5] Update DOCS_GUIDELINES.MD --- docs/DOCS_GUIDELINES.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/DOCS_GUIDELINES.MD b/docs/DOCS_GUIDELINES.MD index 1656fd9c62a..aba983a7c34 100644 --- a/docs/DOCS_GUIDELINES.MD +++ b/docs/DOCS_GUIDELINES.MD @@ -5,7 +5,7 @@ - Check the spelling and grammar, even if you have to copy and paste from an external source. - Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share. - Try to express your thoughts in a concise and clean way. -- Leave a space between the acronyms ADR and ICS and the corresponding number (e.g. ADR 008 or ICS 27). +- Leave a space between the acronyms ADR and ICS and the corresponding number (e.g. ADR 008 and ICS 27). - Don't abuse `code` format when writing in plain English. - Follow Google developer documentation [style guide](https://developers.google.com/style). - Check the meaning of words in Microsoft's [A-Z word list and term collections](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms) (use the search input!). From d11c307cf34ff9a9b7b25e91e40d655bb28e9525 Mon Sep 17 00:00:00 2001 From: crodriguezvega Date: Fri, 13 Jan 2023 15:46:39 +0100 Subject: [PATCH 4/5] review comment --- docs/DOCS_GUIDELINES.MD | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/DOCS_GUIDELINES.MD b/docs/DOCS_GUIDELINES.MD index aba983a7c34..ae3da828bbc 100644 --- a/docs/DOCS_GUIDELINES.MD +++ b/docs/DOCS_GUIDELINES.MD @@ -6,7 +6,7 @@ - Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share. - Try to express your thoughts in a concise and clean way. - Leave a space between the acronyms ADR and ICS and the corresponding number (e.g. ADR 008 and ICS 27). -- Don't abuse `code` format when writing in plain English. +- Don't overuse `code` format when writing in plain English. - Follow Google developer documentation [style guide](https://developers.google.com/style). - Check the meaning of words in Microsoft's [A-Z word list and term collections](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms) (use the search input!). - We recommend using RFC keywords in user documentation (lowercase). The RFC keywords are: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). From 3eed944e34ce2a9c588c2051b0112b45b4da2aed Mon Sep 17 00:00:00 2001 From: crodriguezvega Date: Fri, 13 Jan 2023 15:51:28 +0100 Subject: [PATCH 5/5] review comments --- docs/DOCS_GUIDELINES.MD | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/DOCS_GUIDELINES.MD b/docs/DOCS_GUIDELINES.MD index ae3da828bbc..f22c8804468 100644 --- a/docs/DOCS_GUIDELINES.MD +++ b/docs/DOCS_GUIDELINES.MD @@ -5,7 +5,7 @@ - Check the spelling and grammar, even if you have to copy and paste from an external source. - Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share. - Try to express your thoughts in a concise and clean way. -- Leave a space between the acronyms ADR and ICS and the corresponding number (e.g. ADR 008 and ICS 27). +- Either Leave a space or use a `-` between the acronyms ADR and ICS and the corresponding number (e.g. ADR 008 or ADR-008, and ICS 27 or ICS-27). - Don't overuse `code` format when writing in plain English. - Follow Google developer documentation [style guide](https://developers.google.com/style). - Check the meaning of words in Microsoft's [A-Z word list and term collections](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms) (use the search input!). @@ -13,7 +13,7 @@ ### Links -**NOTE:** Strongly consider the existing links - both within this directory and to the website docs - when moving or deleting files. +**NOTE:** Strongly consider the existing links (both within this directory and to the website docs) when moving or deleting files. Relative links should be used nearly everywhere, due to versioning. Note that in case of page reshuffling, you must update all links references.