[docs] create a new contributors' guide #11669
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
polarweasel
requested review from
aishwarya24,
ymahajan,
lizayugabyte and
ddhodge
|
✔️ Deploy Preview for infallible-bardeen-164bc9 ready! 🔨 Explore the source changes: b885dbb 🔍 Inspect the deploy log: https://app.netlify.com/sites/infallible-bardeen-164bc9/deploys/6222cece88d61a00076fb99e 😎 Browse the preview: https://deploy-preview-11669--infallible-bardeen-164bc9.netlify.app/latest/contribute/docs/ |
✅ Deploy Preview for infallible-bardeen-164bc9 ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
lizayugabyte
reviewed
Mar 7, 2022
added 2 commits
March 25, 2022 17:30
… docs-contributor-guide
ddhodge
reviewed
Mar 29, 2022
| ``` | ||
|
|
||
| 1. Commit your changes. | ||
|
|
There was a problem hiding this comment.
indent this code block more
| @@ -50,25 +66,21 @@ menu: | |||
| | `showAsideToc` | `false` | Should the TOC on the right be enabled | | |||
There was a problem hiding this comment.
| isTocNested | false | Should sub-sections be displayed in the TOC on the right. Set to true. (Content pages only) |
|
|
||
| # Widgets | ||
| ## Widgets | ||
|
|
||
| There are a number of display widgets available. These are listed below. | ||
|
|
There was a problem hiding this comment.
Shortcuts
{{<support-cloud>}} - link to Yugabyte Support form, cloud topic.
and any others
|
|
||
| Content pages contain information about topics. The names of these docs page has the format `my-docs-page.md`. | ||
| **Content pages** contain information about topics. These pages are named in the format `my-docs-page.md`. | ||
|
|
There was a problem hiding this comment.
Links
Make links relative.
Links to pages end in a forward slash (/) and do not include the file suffix.
[Security checklist](../../secure/security-checklist/)
Links to anchors inside pages do not end in a forward slash (/), but note the forward slash that precedes the anchor.
[Limit network exposure](../../secure/security-checklist/#limit-network-exposure)
ddhodge
reviewed
Mar 30, 2022
ddhodge
reviewed
Mar 30, 2022
| showAsideToc: true | ||
| --- | ||
|
|
||
| In this kind of work, the nature of your documentation change means that you'll need to modify existing [_syntax diagrams_](#syntax-diagram) or add new ones. |
There was a problem hiding this comment.
Suggested change
| In this kind of work, the nature of your documentation change means that you'll need to modify existing [_syntax diagrams_](#syntax-diagram) or add new ones. | |
| The API documentation uses [_syntax diagrams_](#syntax-diagram). The following describes diagram maintenance and creation for the YSQL API documentation. (The YCQL documentation uses an old method for syntax diagrams; take advice from colleagues if you need to work on YCQL diagrams.) |
ddhodge
reviewed
Mar 30, 2022
|
|
||
| In this kind of work, the nature of your documentation change means that you'll need to modify existing [_syntax diagrams_](#syntax-diagram) or add new ones. | ||
|
|
||
| > **Note:** The following covers diagram maintenance and creation for the YSQL documentation. The YCQL documentation still uses an old method for this. You must take advice from colleagues if you need to work on YCQL diagrams. |
There was a problem hiding this comment.
Suggested change
| > **Note:** The following covers diagram maintenance and creation for the YSQL documentation. The YCQL documentation still uses an old method for this. You must take advice from colleagues if you need to work on YCQL diagrams. |
ddhodge
reviewed
Mar 30, 2022
|
|
||
| Here is a terse step-by-step summary: | ||
|
|
||
| ### Get set up |
There was a problem hiding this comment.
Suggested change
| ### Get set up | |
| ## Get set up |
ddhodge
reviewed
Mar 30, 2022
|
|
||
| 1. [_Run the generator_](#run-the-generator). This will regenerate every diagram file that is jointly specified by the [_diagram definition file_](#diagram-definition-file) and the set of all [_free-standing generated grammar-diagram pairs_](#free-standing-generated-grammar-diagram-pair). Of course, not all of these newly generated `md` files will differ from their previous versions; `git status` will show you only the ones that actually changed. | ||
|
|
||
| ### Modify or add content pages or syntax rules |
There was a problem hiding this comment.
Suggested change
| ### Modify or add content pages or syntax rules | |
| ## Modify or add content pages or syntax rules |
ddhodge
reviewed
Mar 30, 2022
|
|
||
| > **Note:** There is no tool for link checking within your local git. Broken links are detected when a Yugabyte staff member periodically runs a link checker on the published doc on the Internet. The scope of this check includes _all_ of the Yugabyte properties (for example, the [Blogs site](https://blog.yugabyte.com)). Broken links that this check finds are reported and fixed manually. | ||
|
|
||
| ## 3. Mental model and glossary: creating and maintaining syntax diagrams for YSQL Docs |
There was a problem hiding this comment.
Suggested change
| ## 3. Mental model and glossary: creating and maintaining syntax diagrams for YSQL Docs | |
| ## Mental model and glossary: creating and maintaining syntax diagrams for YSQL Docs |
ddhodge
reviewed
Mar 30, 2022
|
|
||
| > **Note:** The following covers diagram maintenance and creation for the YSQL documentation. The YCQL documentation still uses an old method for this. You must take advice from colleagues if you need to work on YCQL diagrams. | ||
|
|
||
| Once you understand this area, modifying existing [_syntax diagrams_](#syntax-diagram) or adding new ones will seem to be very straightforward. However, you must embrace a fairly large mental model. This, in turn, depends on several terms of art. All this is covered in the dedicated section [Creating and maintaining syntax diagrams for YSQL Docs](#3-mental-model-and-glossary-creating-and-maintaining-syntax-diagrams-for-ysql-docs). |
There was a problem hiding this comment.
Suggested change
| Once you understand this area, modifying existing [_syntax diagrams_](#syntax-diagram) or adding new ones will seem to be very straightforward. However, you must embrace a fairly large mental model. This, in turn, depends on several terms of art. All this is covered in the dedicated section [Creating and maintaining syntax diagrams for YSQL Docs](#3-mental-model-and-glossary-creating-and-maintaining-syntax-diagrams-for-ysql-docs). | |
| Once you understand this area, modifying existing [_syntax diagrams_](#syntax-diagram) or adding new ones will seem to be very straightforward. However, you must embrace a fairly large mental model. This, in turn, depends on several terms of art. All this is covered in the dedicated section [Creating and maintaining syntax diagrams for YSQL Docs](#mental-model-and-glossary-creating-and-maintaining-syntax-diagrams-for-ysql-docs). |
Co-authored-by: Dwight Hodge <79169168+ddhodge@users.noreply.github.com>
… docs-contributor-guide
…yte-db into docs-contributor-guide
… docs-contributor-guide
polarweasel
commented
Apr 8, 2022
added 11 commits
April 7, 2022 19:22
…yte-db into docs-contributor-guide
… docs-contributor-guide
… docs-contributor-guide
… docs-contributor-guide
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
@netlify /latest/contribute/docs/
Notes: