|
| 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