chore(docs): Add some usage docs (#28)

* chore(docs): Add some usage docs

* feat: Add image used in some examples

* Update README.md

Co-authored-by: Ruth John <[email protected]>

---------

Co-authored-by: Ruth John <[email protected]>

Author: bsmth

CONTRIBUTING.md

@@ -6,10 +6,7 @@
 - [Finding an issue](#finding-an-issue)
 - [Asking for help](#asking-for-help)
 - [Pull request process](#pull-request-process)
-- [Setting up the development environment](#setting-up-the-development-environment)
   - [Forking and cloning the project](#forking-and-cloning-the-project)
-  - [Prerequisites](#prerequisites)
-- [Signing commits](#signing-commits)
 
 Welcome 👋 Thank you for your interest in contributing to MDN Web Docs. We are happy to have you join us! 💖
 
@@ -26,8 +23,6 @@ If anything doesn't make sense or work as expected, please open an issue and let
 
 We welcome many different types of contributions including:
 
-<!-- TODO: These are not set in stone and should be reconsidered per project based on needs. -->
-
 - New features and content suggestions.
 - Identifying and filing issues.
 - Providing feedback on existing issues.
@@ -50,68 +45,13 @@ Also, mention the community team using the `@mdn/mdn-community-engagement` handl
 
 ## Asking for help
 
-The best way to reach us with a question when contributing is to use the following channels in the following order of precedence:
-
-- [Start a discussion](https://github.com/orgs/mdn/discussions)
-- Ask your question or highlight your discussion on [Matrix](https://matrix.to/#/#mdn:mozilla.org).
-- File an issue and tag the community team using the `@mdn/mdn-community-engagement` handle.
+The best way to contact us with a question when contributing is to reach out to us in [one of our communication channels](https://developer.mozilla.org/en-US/docs/MDN/Community/Communication_channels).
 
 ## Pull request process
 
 The MDN Web Docs project has a well-defined pull request process which is documented in the [Pull request guidelines](https://developer.mozilla.org/en-US/docs/MDN/Community/Pull_requests).
 Make sure you read and understand this process before you start working on a pull request.
 
-## Setting up the development environment
-
-<!-- TODO -->
-
 ### Forking and cloning the project
 
 The first step in setting up your development environment is to [fork the repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) and [clone](https://docs.github.com/en/get-started/quickstart/fork-a-repo#cloning-your-forked-repository) the repository to your local machine.
-
-<!--
-
-TODO
-
-### Prerequisites
-
-A section here that describes the steps needed to prepare a local machine before building.
-It should look like this:
-
-To get started, make sure you have the following:
-
-- [NVM](https://github.com/nvm-sh/nvm) or [NVM for Windows](https://github.com/coreybutler/nvm-windows)
-- [Nodejs](https://nodejs.org/en/) (Latest stable release or up to two versions back)
-
-### Building the project
-
-Add a section here that describes the steps needed to build this project.
-It should follow the same structure as the following example:
-
-Once you have the above installed and have the repository cloned, it is time to install the project dependencies.
-
-```bash
-npm i
-```
-
-With the dependencies installed you can start the project with the following command:
-
-```bash
-npm start
-```
-
-Open `http://localhost:3000` in your browser.
-
-To run the test suite, use the following command:
-
-```bash
-npm test
-```
-
--->
-
-## Signing commits
-
-We require all commits to be signed to verify the author's identity.
-GitHub has a detailed guide on [setting up signed commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits).
-If you get stuck, please [ask for help](#asking-for-help).

README.md

@@ -2,29 +2,69 @@
 
 This repository contains shared media assets for MDN Web Docs, including source files where available.
 
-The assets are hosted at https://mdn.github.io/shared-assets/, so use the `mdn.github.io` URLs in MDN content.
+The assets are hosted at <https://mdn.github.io/shared-assets/>, so use the `mdn.github.io` URLs in MDN content.
 
-<!--
+## Getting started
 
-TODO:
+If you are creating a live sample on MDN that requires assets (images, fonts) to demonstrate a feature, you can use these resources instead of adding new ones to the content repositories.
 
-## Getting Started
+### Using shared assets in documentation
 
-To get up and running, follow these steps:
+If you are working on MDN documentation, you can refer to images in markdown like so (suitable for diagrams):
 
-Include enough details to get started using the project here and link to other docs with more detail as needed.
-This should look like:
+```markdown:
+![Diagram of a preflight request](https://mdn.github.io/shared-assets/images/diagrams/http/cors/preflight-correct.svg)
+```
 
-- quick installation/build instructions
-- a few simple examples of use
+If you want to use assets in code samples, you can refer to them like this for fonts, for example:
 
-More detailed build instructions (e.g., prerequisites and testing hints) should be in the CONTRIBUTING.md file.
--->
+```css
+@font-face {
+  src: url("https://mdn.github.io/shared-assets/fonts/LeagueMono-VF.ttf");
+  font-family: "LeagueMonoVariable";
+  /* etc. */
+}
+```
+
+Images are also similar in CSS:
+
+```css
+body {
+  background: url("https://mdn.github.io/shared-assets/images/examples/leopard.jpg")
+    #00d no-repeat fixed;
+}
+```
+
+And in HTML, for example:
+
+```html
+<img
+  alt="colorful balloon against a blue sky"
+  src="https://mdn.github.io/shared-assets/images/examples/balloon.jpg"
+/>
+```
+
+### Adding new assets
+
+First, check if the shared assets repository (this repo) already contains a suitable existing resource.
+If there is nothing appropriate, you may open a pull request that adds new resources.
+Make sure you've checked the following things:
+
+- compress resources such as images to conserve bandwidth on live pages
+- the resources are [CC0](https://creativecommons.org/public-domain/cc0/) or are under a permissive license
+- there is a need to add the resource instead of using existing ones
+
+Your pull request must include:
+
+- rationale for adding a resource, and
+- links to licensing terms of the asset(s).
+
+Once assets are added to the `main` branch, they will be available at `https://mdn.github.io/shared-assets/path/to/new/asset`.
 
 ## Contributing
 
 Our project welcomes contributions from any member of our community.
-To get started contributing, please see our [Contributor Guide](CONTRIBUTING.md).
+If you want to find out more, you can see helpful links in our [Contributor Guide](CONTRIBUTING.md).
 
 By participating in and contributing to our projects and discussions, you acknowledge that you have read and agree to our [Code of Conduct](CODE_OF_CONDUCT.md).
 
@@ -38,4 +78,4 @@ This project is licensed under the [LICENSE](LICENSE.md).
 
 ### Attributions
 
-- The font `fonts/font_with_slant_axis.woff2` was created by https://github.com/arrowtype and is used under the OFL license.
+- The font `fonts/font_with_slant_axis.woff2` was created by <https://github.com/arrowtype> and is used under the OFL license.