Update README.md

xtyuns · May 19, 2022 · 0295d90 · 0295d90
1 parent 781ed5b
commit 0295d90
Showing 1 changed file with 32 additions and 25 deletions.
diff --git a/README.md b/README.md
@@ -1,45 +1,52 @@
-We use [docusaurus](https://v2.docusaurus.io/) to power [docs.getdbt.com](https://docs.getdbt.com/).
+_We use [docusaurus](https://v2.docusaurus.io/) to power [docs.getdbt.com](https://docs.getdbt.com/)._
 
-## Contributing
+#### Table of Contents
+* [Contributing](#contributing)  
+* [Writing content](#writing-content)
+* [Running the docs site locally](#running-the-docs-site-locally)
+
+# Contributing
 
 We welcome contributions from community members to this repo:
-- **Fixes**: If you notice an error (there are likely many), use the `Edit this page` button at the bottom of each page to suggest a change. We recommend you contribute small changes directly from the GitHub interface.
-- **New documentation**: If you contributed code in [dbt-core](https://github.com/dbt-labs/dbt-core), we encourage you to also write the docs here!
-- **Refactors**: At this time, we are unable to support community members who wish to re-write sections of docs.getdbt.com. We hope to change this in the future!
+- **Fixes**: When you notice an error, you can use the `Edit this page` button at the bottom of each page to suggest a change. 
+- **New documentation**: If you contributed code in [dbt-core](https://github.com/dbt-labs/dbt-core), we encourage you to also write the docs here! Please reach out in the dbt community if you need help finding a place for these docs.
+- **Major rewrites**: You can [file an issue](https://github.com/dbt-labs/docs.getdbt.com/issues/new?assignees=&labels=content%2Cimprovement&template=improve-docs.yml) or [start a discussion](https://github.com/dbt-labs/docs.getdbt.com/discussions) to propose ideas for a content area that requires attention.
+
+You can use components documented in the [docusaurus library](https://v2.docusaurus.io/docs/markdown-features/). 
+
+# Writing content
+
+When writing content, you should refer to the style guide (TBD) and [content types](/contributing/content-types.md) to help you understand our writing standards and how we break down information in the product documentaion. 
 
-## Using the style guide
+## Using the content style guide
 
-[TBD] a style guide to help you write along the dbt style guidelines. 
+[TBD] a style guide to help you write in a consistent, accessible, and inclusive style. 
 
-## Versioning
+## Versioning content
 
 We now provide dynamic versioning in the dbt Labs product documentation. To learn more about how to version the docs for dbt Core, see [Managing available versions](/contributing/versioningdocs.md).
 
-## Adding to the glossary 
+## Adding content to the glossary 
 
 [TBD] a how-to guide on the programming behind glossary entries. 
 
-## Running the Docs site locally
+# Running the Docs site locally
 
 You can click a link available in a netlify bot PR comment to see and review your changes rendered on a staging server. You are also able to see and review your proposed modifications locally on your computer. Our setup instructions use [homebrew](https://brew.sh/):
 
-0. If applicable, install [Xcode Command Line Tools](https://developer.apple.com/download/more/); you'll likely need an AppleID for this. You will also need [homebrew](https://brew.sh/). 
-2. Install `node`: `brew install node`
-3. Clone this repo: `git clone [email protected]:fishtown-analytics/docs.getdbt.com.git`
-4. `cd` into the repo: `cd docs.getdbt.com`
-5. `cd` into the `website` subdirectory: `cd website`
-6. Install the required node packages: `npm install`
-7. Build the website: `npm start`
-8. Before pushing your changes to a branch, check that all links work by using the `make build` script.
+## prerequisites
+* Install [Xcode Command Line Tools](https://developer.apple.com/download/more/); you'll likely need an AppleID for this. 
+* Install [homebrew](https://brew.sh/). 
+
+1. Install `node`: `brew install node`
+2. Clone this repo: `git clone [email protected]:fishtown-analytics/docs.getdbt.com.git`
+3. `cd` into the repo: `cd docs.getdbt.com`
+4. `cd` into the `website` subdirectory: `cd website`
+5. Install the required node packages: `npm install`
+6. Build the website: `npm start`
+7. Before pushing your changes to a branch, check that all links work by using the `make build` script.
 
 Advisory: 
 - Currently an `npm install` produces a number of dependency warnings, in particular several claiming that `docusaurus/core` is missing. Rest assured, this message is a red herring. As of writing this, no 2.0.0 package exists, so you won't have much luck trying to install it. Feel free to ignore those warnings.
 - If you run into an `fatal error: 'vips/vips8' file not found` error when you run `npm install`, you may need to run `brew install vips`. Warning: this one will take a while -- go ahead and grab some coffee!
 
-You can also check out [this Loom video](https://www.loom.com/share/7037780b86eb4f16953664b8f15f1e21) that I recorded for co-workers — it covers setting up docs.getdbt.com locally, and adding a page with links and images. Heads up — this was very much something I did on the fly, so is not super polished!
-
-## Custom components
-
-Check out [docs.getdbt.com/styles](https://docs.getdbt.com/styles) for examples of different components that can be used in these docs.
-
-You can also use components directly from the [docusaurus library](https://v2.docusaurus.io/docs/markdown-features/).