Skip to content

Commit 3d92c4b

Browse files
Copilothawkeyexl
Copilot
and
hawkeyexl
authored
Overhaul documentation contribution guidelines to lower barriers and empower all contributors (#98)
* Initial plan * Add core contribution guides and first templates Co-authored-by: hawkeyexl <[email protected]> * Add remaining templates, GitHub integration, and Vale configuration Co-authored-by: hawkeyexl <[email protected]> * Initial edits * Light revisions * Syntax fixes * Revise documentation for clarity and consistency - Update tone guidelines to avoid using "please" in instructions - Change titles and labels for consistency across documents - Improve examples by replacing "❌" with "⛔" for clarity - Enhance instructions and formatting in various templates * Update contribution guidelines for consistency - Change section titles from "Quick fixes" to "Quick changes" - Change section titles from "Standard contributions" to "Standard changes" - Change section titles from "Substantial contributions" to "Substantial changes" - Update guide links to match new section titles * - Update title and sidebar label for consistency in documentation - Revise section headings for clarity * - Standardize title and sidebar label casing in review process documentation. - Clarify timeline expectations with punctuation. - Enhance clarity in automated checks section. - Improve instructions for handling Vale suggestions. - Update substantial contributions guidelines for clarity and completeness. - Add import statements for Tabs and TabItem components. - Refine contribution planning steps with additional details. - Streamline content structure and improve readability throughout. * - Comment out the "contributing/testing" entry in the sidebars configuration. * Refactor issue templates for improved clarity and consistency - Change 'about' to 'description' in documentation bug, feature, and question templates. - Update body structure to include clear labels and descriptions for each input field. - Enhance user guidance with descriptive placeholders and validation requirements. * Ran through formatter * Update Vale workflow to include dependency setup - Add step to install mdx2vast before running Vale * Change vale action * Remvoe blog paths * Refactor documentation templates for consistency and clarity - Standardize titles and sidebar labels across templates - Update code block formatting for better readability - Improve example structures and explanations - Remove unnecessary markdown syntax for cleaner output --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: hawkeyexl <[email protected]> Co-authored-by: hawkeyexl <[email protected]>
1 parent 016dc0a commit 3d92c4b

23 files changed

+4223
-22
lines changed

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Discord Community
4+
url: https://discord.gg/2M7wXEThfF
5+
about: Ask questions and discuss with the community
6+
- name: Documentation
7+
url: https://doc-detective.com/docs
8+
about: Browse the Doc Detective documentation

‎.github/ISSUE_TEMPLATE/documentation-bug.yml‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
name: Documentation Bug Report
2+
description: Report an error, outdated information, or broken link in the documentation
3+
title: '[Docs Bug] '
4+
labels: ['documentation', 'bug']
5+
assignees: []
6+
body:
7+
- type: input
8+
id: url
9+
attributes:
10+
label: Page or section affected
11+
description: Provide the URL or path to the documentation page with the issue
12+
placeholder: 'https://doc-detective.com/docs/...'
13+
validations:
14+
required: true
15+
16+
- type: textarea
17+
id: whats-wrong
18+
attributes:
19+
label: What's wrong?
20+
description: Describe the issue clearly. What's incorrect, missing, or broken?
21+
validations:
22+
required: true
23+
24+
- type: textarea
25+
id: should-say
26+
attributes:
27+
label: What should it say instead?
28+
description: If you know what the correct information should be, describe it here
29+
validations:
30+
required: false
31+
32+
- type: textarea
33+
id: steps-to-reproduce
34+
attributes:
35+
label: Steps to reproduce (if applicable)
36+
description: If this is about a procedure that doesn't work, list the steps you followed
37+
placeholder: |
38+
1.
39+
2.
40+
3.
41+
validations:
42+
required: false
43+
44+
- type: textarea
45+
id: expected-result
46+
attributes:
47+
label: Expected result
48+
description: What did you expect to happen or see?
49+
validations:
50+
required: false
51+
52+
- type: textarea
53+
id: actual-result
54+
attributes:
55+
label: Actual result
56+
description: What actually happened or what did you see?
57+
validations:
58+
required: false
59+
60+
- type: textarea
61+
id: screenshots
62+
attributes:
63+
label: Screenshots (optional)
64+
description: Add screenshots to help explain the problem
65+
validations:
66+
required: false
67+
68+
- type: textarea
69+
id: additional-context
70+
attributes:
71+
label: Additional context
72+
description: Any other information that might be helpful
73+
validations:
74+
required: false
75+
76+
- type: checkboxes
77+
id: willing-to-fix
78+
attributes:
79+
label: Are you willing to fix this?
80+
description: Would you like to submit a pull request to fix this issue?
81+
options:
82+
- label: Yes, I can fix this
83+
- label: No, but I can provide more information if needed

‎.github/ISSUE_TEMPLATE/documentation-feature.yml‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
name: Documentation Feature Request
2+
description: Suggest new documentation or improvements to existing content
3+
title: '[Docs Feature] '
4+
labels: ['documentation', 'enhancement']
5+
assignees: []
6+
body:
7+
- type: textarea
8+
id: what-is-missing
9+
attributes:
10+
label: What documentation is missing or needs improvement?
11+
description: Describe what documentation you'd like to see added or improved
12+
validations:
13+
required: true
14+
15+
- type: textarea
16+
id: who-benefits
17+
attributes:
18+
label: Who would benefit from this?
19+
description: Describe the audience and use case
20+
validations:
21+
required: true
22+
23+
- type: textarea
24+
id: describe-docs
25+
attributes:
26+
label: Describe the documentation you'd like
27+
description: What should this documentation cover? Be as specific as possible
28+
validations:
29+
required: true
30+
31+
- type: textarea
32+
id: suggested-structure
33+
attributes:
34+
label: Suggested structure or outline (optional)
35+
description: If you have ideas about how this documentation should be organized, share them here
36+
validations:
37+
required: false
38+
39+
- type: textarea
40+
id: examples
41+
attributes:
42+
label: Examples from other projects (optional)
43+
description: Link to similar documentation from other projects that you find helpful
44+
validations:
45+
required: false
46+
47+
- type: textarea
48+
id: additional-context
49+
attributes:
50+
label: Additional context
51+
description: Any other information that would help us understand your request
52+
validations:
53+
required: false
54+
55+
- type: checkboxes
56+
id: willing-to-write
57+
attributes:
58+
label: Are you willing to write this?
59+
description: Would you like to submit a pull request to add this documentation?
60+
options:
61+
- label: Yes, I can write this documentation
62+
- label: No, but I can review/provide feedback on drafts
63+
- label: No, I'm requesting that someone else write it

‎.github/ISSUE_TEMPLATE/documentation-question.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Documentation Question
2+
description: Ask a question about the documentation
3+
title: '[Docs Question] '
4+
labels: ['documentation', 'question']
5+
assignees: []
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: |
10+
**Note:** For general questions about using Doc Detective, please consider:
11+
- Joining our [Discord community](https://discord.gg/2M7wXEThfF)
12+
- Checking the [documentation](https://doc-detective.com/docs)
13+
- Searching existing [issues](https://github.com/doc-detective/doc-detective.github.io/issues)
14+
15+
Use this issue template if you have a specific question about the documentation itself (not about using Doc Detective).
16+
17+
- type: textarea
18+
id: question
19+
attributes:
20+
label: Your question
21+
description: What would you like to know?
22+
validations:
23+
required: true
24+
25+
- type: textarea
26+
id: what-tried
27+
attributes:
28+
label: What have you tried?
29+
description: What documentation have you already read? What did you try?
30+
validations:
31+
required: false
32+
33+
- type: textarea
34+
id: context
35+
attributes:
36+
label: Context
37+
description: Why do you need this information? What are you trying to accomplish?
38+
validations:
39+
required: false
40+
41+
- type: textarea
42+
id: additional-info
43+
attributes:
44+
label: Additional information
45+
description: Any other details that might be relevant
46+
validations:
47+
required: false

‎.github/pull_request_template.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
## Description
2+
3+
<!-- Briefly describe the changes in this pull request -->
4+
5+
## Type of contribution
6+
7+
<!-- Check the type that best describes your contribution -->
8+
9+
- [ ] Quick change (typo, broken link, small wording change)
10+
- [ ] Standard change (new content, examples, or improvements)
11+
- [ ] Substantial change (new feature docs, major restructuring, tutorials)
12+
13+
## Related issue
14+
15+
<!-- Link to related issue(s) if applicable -->
16+
17+
Closes # Related to #
18+
19+
## Changes made
20+
21+
<!-- List the specific changes you made -->
22+
23+
-
24+
-
25+
-
26+
27+
## Testing performed
28+
29+
<!-- Describe how you tested your changes -->
30+
31+
- [ ] Previewed changes locally (`npm run start`)
32+
- [ ] Tested all code examples
33+
- [ ] Verified all links work
34+
- [ ] Ran build successfully (`npm run build`)
35+
- [ ] Ran style checks with Vale (if applicable)
36+
- [ ] Added/updated Doc Detective tests (if applicable)
37+
38+
## Screenshots (if applicable)
39+
40+
<!-- Add screenshots to show visual changes -->
41+
42+
## Checklist
43+
44+
<!-- Mark items as complete with [x] -->
45+
46+
- [ ] I have signed the [Contributor License Agreement](https://cla-assistant.io/doc-detective/doc-detective.github.io)
47+
- [ ] My changes follow the [contribution guidelines](/docs/contributing/)
48+
- [ ] I have used the appropriate [content template](/docs/contributing/templates/) (if applicable)
49+
- [ ] All new content files use `.mdx` extension
50+
- [ ] Front matter is included on all new pages
51+
- [ ] Links use absolute paths (e.g., `/docs/page` not `../page`)
52+
- [ ] Code examples are complete and tested
53+
- [ ] I have spell-checked my changes
54+
- [ ] I have reviewed my own changes for errors
55+
56+
## Additional notes
57+
58+
<!-- Any additional information reviewers should know -->
59+
60+
---
61+
62+
**For reviewers:**
63+
64+
- See [Review Process](/docs/contributing/review-process) for guidelines
65+
- Focus on technical accuracy and user value
66+
- Don't block on minor style issues—automation handles those

‎.github/workflows/vale.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: Vale Style Checks
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- 'docs/**/*.md'
7+
- 'docs/**/*.mdx'
8+
9+
jobs:
10+
vale:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: Checkout code
14+
uses: actions/checkout@v4
15+
16+
- name: Set up dependencies
17+
run: npm install -g mdx2vast
18+
19+
- name: Run Vale
20+
uses: errata-ai/[email protected]
21+
with:
22+
files: "docs/"
23+
fail_on_error: false
24+
filter_mode: nofilter
25+
env:
26+
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

‎AGENTS.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -155,13 +155,13 @@ All documentation must follow the [Google Developer Style Guide](https://develop
155155
**Voice and Tone:**
156156
- Write conversationally and friendly, like a knowledgeable friend, without being frivolous or overly colloquial
157157
- Avoid buzzwords, jargon, exclamation marks (except rare exciting moments), and phrases like "simply" or "it's easy"
158-
- Don't use "please" in instructions: ✅ "Click **View**" not ❌ "Please click **View**"
158+
- Don't use "please" in instructions: ✅ "Click **View**" not ⛔ "Please click **View**"
159159

160160
**Language and Grammar:**
161161
- Use second person ("you") rather than first person ("we")
162-
- Use active voice: ✅ "Click the button" not ❌ "The button can be clicked"
163-
- Use present tense: ✅ "The API returns data" not ❌ "The API will return data"
164-
- Put conditions before instructions: ✅ "If you want to save, click **Save**" not ❌ "Click **Save** if you want to save"
162+
- Use active voice: ✅ "Click the button" not ⛔ "The button can be clicked"
163+
- Use present tense: ✅ "The API returns data" not ⛔ "The API will return data"
164+
- Put conditions before instructions: ✅ "If you want to save, click **Save**" not ⛔ "Click **Save** if you want to save"
165165

166166
**Formatting:**
167167
- Use sentence case for headings (not Title Case)
@@ -173,8 +173,8 @@ All documentation must follow the [Google Developer Style Guide](https://develop
173173

174174
**Examples of Tone:**
175175
- ✅ Good: "To get the user's phone number, call `user.phoneNumber.get`."
176-
- ❌ Too casual: "Dude! This API is totally awesome!"
177-
- ❌ Too formal: "The telephone number can be retrieved by the developer via the simple expedient of using the get method."
176+
- ⛔ Too casual: "Dude! This API is totally awesome!"
177+
- ⛔ Too formal: "The telephone number can be retrieved by the developer via the simple expedient of using the get method."
178178

179179
### The Good Docs Project Templates
180180

0 commit comments

Comments
 (0)