Skip to content

Commit d382233

Browse files
marcysuttonDSchau
authored andcommitted
feat: add contributing docs re-organization (#29)
The Gatsby.js docs, while wonderful, are light on coding instructions for contributors. With dedicated sections in the Contributing docs, it will be easier to learn how to clone the repository, where to find certain things like docs or plugins, how to run tests, and insider infrastructure knowledge required to submit a successful pull request on the first try. A lot of this information already lives on the "How to Contribute" page, but it's buried. It would help discoverability if this information lived on separate pages. Doing this means we can easily add a new section on "Setting up test environments", such as using Docker to hook up an easy Wordpress test installation. I would love to hear your feedback as this is my first Gatsby RFC. I'm totally open to suggestions!
1 parent bbc951b commit d382233

File tree

1 file changed

+71
-0
lines changed

1 file changed

+71
-0
lines changed

text/docs-code-contributions.md

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
- Start Date: 2019-02-07)
2+
- RFC PR:
3+
- Gatsby Issue:
4+
5+
# Summary
6+
7+
Reorganize the contributor documentation to aid in Gatsby core and docs development.
8+
9+
# Motivation
10+
11+
The Gatsby.js docs, while wonderful, are light on coding instructions for contributors. With dedicated sections in the Contributing docs, it will be easier to learn how to clone the repository, where to find certain things like docs or plugins, how to run tests, and insider infrastructure knowledge required to submit a successful pull request on the first try.
12+
13+
A lot of this information already lives on the "How to Contribute" page, but it's buried. It would help discoverability if this information lived on separate pages.
14+
15+
# Detailed design
16+
17+
I propose that we add some pages to the existing contributor documentation and move some content around. Here is an IA diagram that (briefly) reflects the current structure and what I think we should add (open for discussion, of course):
18+
19+
Docs
20+
- Guides
21+
- Ecosystem
22+
- API Reference
23+
- Releases & Migration
24+
- Conceptual Guide
25+
- Behind the Scenes
26+
- Advanced Tutorials
27+
28+
Contributing
29+
- Community
30+
- Why Contribute to Gatsby?
31+
- Pair Programming Sessions
32+
- Free Swag for Contributors
33+
- Where to Participate in the Community
34+
- How to Run a Gatsby Workshop
35+
- How to Pitch Gatsby
36+
- Code of Conduct
37+
- Gatsby Style Guide
38+
- How to Contribute
39+
* How to File an Issue
40+
* How to Label an Issue
41+
* Triaging GitHub Issues
42+
* Docs Contributions
43+
* Blog & Website Contributions
44+
* Code Contributions
45+
* Setting up your Local Dev Environment
46+
* Community Contributions
47+
- Submit to Site Showcase
48+
- Submit to Creator Showcase
49+
- Submit to Starter Library
50+
- Submit to Plugin Library
51+
- RFC Process
52+
- Gatsby's Governance Model*
53+
54+
# Drawbacks
55+
56+
Why should we *not* do this? Please consider:
57+
58+
- we will need some redirects so people who have bookmarked things don't get 404s
59+
- there will be a user adjustment required to learn the new locations of things
60+
61+
# Alternatives
62+
63+
Adding more top-level docs instead of reorganizing them. It's a pretty large section though, and it seems like it could be reorganized.
64+
65+
# Adoption strategy
66+
67+
If we implement this, I will move some pages and content around and fill in missing gaps. There may be additional subpages added for more detailed technical instructions.
68+
69+
# Unresolved questions
70+
71+
How do people feel about this idea?

0 commit comments

Comments
 (0)