Skip to content

Commit 79be246

Browse files
authored
Add contributing and style guides for documentation (#1013)
* Add fixed data files * Add contributing and style guides for documentation * Update md-style-guide.md Integrate Benjamin's comments into style-guide.md * Update CONTRIBUTING-docs.md Include Benjamin's comments in CONTRIBUTING-docs.md
1 parent 34e59ce commit 79be246

File tree

8 files changed

+264
-101
lines changed

8 files changed

+264
-101
lines changed

CONTRIBUTING.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ To publish a case study, we encourage you to join `#adopters` channel in our [Sl
6161

6262
### 📋 Improving the Documentation
6363

64-
If you would like to join the efforts to improve the JSON Schema Documentation, we encourage you to check our [documentation board](https://github.com/orgs/json-schema-org/projects/16) to get a sense of the pending issues and who is doing what. We encourage you to join the discussion on the [issue #421](https://github.com/json-schema-org/community/issues/421) so you can see the long term vision for our docs. We also invite you to join the discussion in `#documentation` channel in our [Slack workspace](https://json-schema.org/slack).
64+
Want to help us improve the JSON Schema documentation? Check out our Contributing guide for docs and Style guide. These documents will give you the basics of our processes to get you started and text-formatting guidelines to create consistent documentation for JSON Schema.
6565

6666
### 🌐 Improving the Website
6767

data/community-users.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -569,4 +569,4 @@
569569
"avatar_url": "https://avatars.githubusercontent.com/u/30574738?v=4",
570570
"html_url": "https://github.com/kalivtrope"
571571
}
572-
]
572+
]

pages/CONTRIBUTING-docs.md

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# JSON Schema documentation contributing guide
2+
3+
This guide describes the workflow to contribute to the JSON Schema technical documentation. If you would like to contribute to other aspects of the JSON Schema website, like writing blog articles or publishing a case study, please read the website's [Contributing Guide](/website/CONTRIBUTING.md) for more details.
4+
5+
## Welcome
6+
Thank you for helping us improve our documentation.
7+
8+
This guide is intended for use by documentation contributors and will help you get started with the basics of our working processes.
9+
10+
## Before you start
11+
To contribute to the JSON Schema documentation you will need to complete the following steps:
12+
13+
1. [Create a GitHub account](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github), if you don't have one already.
14+
2. Read our [Code of Conduct](https://json-schema.org/overview/code-of-conduct).
15+
3. [Install the JSON Schema website](https://github.com/json-schema-org/website/blob/main/INSTALLATION.md) on your computer.
16+
4. Read our style guide.
17+
18+
## Community engagement
19+
To stay updated with news about the JSON Schema project and its documentation, engage with our team, ask questions, and discuss ideas, please join our [Slack workspace](https://json-schema.org/slack). We particularly recommend the following channels:
20+
21+
- #documentation: Discussions related to the JSON Schema documentation.
22+
23+
- #website: Discussions related to our website.
24+
25+
- #introductions: Self-introductions and connecting with other members of the community.
26+
27+
- #community-announcements: Events and updates related to the JSON Schema project.
28+
29+
- #anouncements: Important announcement from the JSON Schema organization.
30+
31+
- #stack-overflow: Stack overflow questions tagged with JSON Schema.
32+
33+
## Best practices
34+
35+
This is a list of best practices the JSON Schema project strives for and resources we recommend for additional information:
36+
37+
1. File and branching naming conventions: We use dashes instead of spaces, and lowercase letters to name .md files and branches. For example: `implementers-guide.md`, `web-feat-diataxis`.
38+
2. Commit messages: To learn how to write good commit messages, see [Step-by-step guide on how to write good commit messages on Git](https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/).
39+
40+
## Contribution workflow
41+
42+
Here we describe three ways you can help us improve our documentation:
43+
44+
45+
1. Review pull requests
46+
2. Work on an existing issue
47+
3. Propose changes
48+
49+
### Review pull requests
50+
51+
Are you new to the JSON Schema community? Help us review pull requests. Reviewing pull requests helps you familiarize yourself with our workflows, learn how others contribute, and understand the project's needs and goals. It's a great way to start contributing and you'll be better prepared to make your own contributions.
52+
53+
### Work on an existing issue
54+
55+
To work on an existing issue, go to the [JSON Schema docs board](https://github.com/orgs/json-schema-org/projects/16) and check all the open issues.
56+
57+
If the issue you select has no assignees, you can claim the issue by assigning it to yourself and tag @json-schema-org/docs-team in the comments to let us know you'll be working on it.
58+
59+
If the issue you select has already an assignee, write a comment expressing your interest in collaborating with them. The JSON Schema respects the order in which people claim issues, therefore, you will have to check if the assignee is accepting collaborations.
60+
61+
After you have been assigned to an issue, fork the [json-schema-org/website](https://github.com/json-schema-org/website) repository and create a new branch from `main` to work on the changes.
62+
63+
### Propose changes
64+
65+
To propose modifications to our documentation that do not have an issue in the [documentation board](https://github.com/orgs/json-schema-org/projects/16), you can [create a GitHub issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue#creating-an-issue-from-a-repository) and use the *Documentation* template to describe the changes. After that, you can decide whether you want to work on the changes yourself or let someone else claim the issue. If you decide to work on the issue, assign it to yourself and commit the changes to a new branch.
66+
67+
## Create a Pull Request
68+
69+
To submit your work to review by the community, open a draft pull request to the `main` upstream branch, and add the issue your pull request solves. Add @json-schema-org/docs-team as a reviewer of your pull request, and let us know in the #documentation Slack channel your pull request is ready for review.
70+
71+
The reviewers might ask for additional changes. When they approve your pull request, you can merge your changes into `main` and your contribution to the project will be complete!
72+
73+
<br>
74+
75+
We created this guide based on templates from [The Good Docs Project](https://www.thegooddocsproject.dev/).

0 commit comments

Comments
 (0)