Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove meta site #20775

Merged
merged 35 commits into from
Oct 12, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
3034628
docs(contributing): details about adding images to video guide
bsmth Sep 15, 2022
6416cd0
docs(contributing): details about code examples
bsmth Sep 15, 2022
92063d0
docs(contributing): add browser-compat-data guide
bsmth Sep 15, 2022
a0b8893
docs(contributing): add deployment timeline guide
bsmth Sep 15, 2022
ccd37a1
docs(contributing): add external files doc
bsmth Sep 15, 2022
2e4e003
docs(contributing): add content reuse policy
bsmth Sep 15, 2022
0f34244
docs(contributing): add prio list
bsmth Sep 15, 2022
c25e807
chore(meta): Delete meta site
bsmth Sep 15, 2022
fb78d1d
Merge remote-tracking branch 'upstream/main' into remove-meta-site
bsmth Sep 15, 2022
bf65039
chore(URLs): fix URLs to use root-relative format
bsmth Sep 15, 2022
9c51864
chore(docs): use md instead of HTML
bsmth Sep 15, 2022
7ba2e12
Merge remote-tracking branch 'upstream/main' into remove-meta-site
bsmth Sep 19, 2022
f984dc8
chore(docs): use slug of previous content
bsmth Sep 19, 2022
352dd1e
chore(docs): Documentation priorities
bsmth Sep 19, 2022
35a3b7c
chore(docs): Documentation priorities
bsmth Sep 19, 2022
eaa39fc
chore(docs): rename dir to documentation_priorities
bsmth Sep 19, 2022
6b319ff
chore(docs): remove Netlify.toml config
bsmth Sep 19, 2022
cd033b2
Merge branch 'main' into remove-meta-site
bsmth Sep 19, 2022
f108aed
Apply suggestions from code review
bsmth Sep 20, 2022
c529aeb
update from main
bsmth Sep 20, 2022
9cd3de4
chore(docs): changes following reviewer feedback
bsmth Sep 20, 2022
164003c
chore(docs): remove redundant code examples page
bsmth Sep 20, 2022
1132f41
chore(docs): remove redundant BCD page
bsmth Sep 20, 2022
6a3ec97
chore(docs): merge content reuse notes with attrib page
bsmth Sep 20, 2022
5d00933
Update files/en-us/mdn/community/pull_requests/index.md
bsmth Sep 20, 2022
5d3a6b1
Merge branch 'main' into remove-meta-site
bsmth Sep 22, 2022
400f364
chore(docs): BCD data page cleanup and reference BCD repo contributin…
bsmth Sep 22, 2022
1e70383
chore(docs) remove docs priorities document
bsmth Sep 22, 2022
1bac839
Merge branch 'main' into remove-meta-site
bsmth Oct 5, 2022
dc084f5
docs(conbtrib): improvements on deploy times for related repos
bsmth Oct 6, 2022
323ea2c
Merge branch 'main' into remove-meta-site
bsmth Oct 6, 2022
52a822b
docs(conbtrib): remove references to unvetted tools
bsmth Oct 6, 2022
002f27a
chore(docs) remove external-content.md
bsmth Oct 6, 2022
de92aec
Merge branch 'main' into remove-meta-site
bsmth Oct 12, 2022
45a1953
Merge branch 'main' into remove-meta-site
bsmth Oct 12, 2022
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion files/en-us/_redirects.txt
Original file line number Diff line number Diff line change
Expand Up @@ -5407,7 +5407,6 @@
/en-US/docs/MDN/Contribute/Content/Specification_tables /en-US/docs/MDN/Writing_guidelines/Page_structures/Specification_tables
/en-US/docs/MDN/Contribute/Content/Style_guide /en-US/docs/MDN/Writing_guidelines/Writing_style_guide
/en-US/docs/MDN/Contribute/Creating_and_editing_pages /en-US/docs/MDN/Writing_guidelines/Howto/Creating_moving_deleting
bsmth marked this conversation as resolved.
Show resolved Hide resolved
/en-US/docs/MDN/Contribute/Documentation_priorities https://mdn-contributor-docs.mozilla.org/legacy/documentation-priorities/
/en-US/docs/MDN/Contribute/Does_this_belong /en-US/docs/MDN/Writing_guidelines/What_we_write
/en-US/docs/MDN/Contribute/Editor/Live_samples /en-US/docs/MDN/Writing_guidelines/Page_structures/Live_samples
/en-US/docs/MDN/Contribute/FAQ /en-US/docs/MDN/Contribute
Expand Down
4 changes: 1 addition & 3 deletions files/en-us/mdn/community/issues/issue_triage/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,9 +103,7 @@ Definitions:
- Major issue — Something that could severely affect a page's usefulness, for example a significant amount of out-of-date information, a complex and important code example that doesn't work, a significant amount of prose that is badly written and hard to understand, a large number of broken links, etc.
- Minor issue — something that doesn't look great but does not affect learning, or only has a minor effect on learning. Examples — Typos, bad grammar, a broken link, a small amount of out-of-date information or badly-written prose, a small code snippet that doesn't work.

Generally speaking, critical issues should be fixed immediately, and would probably be handled by MDN staff/peers. And Tier 1 issues are more important than Tier 2 issues. Folks that are interested in tackling the highest priority MDN issues should always tackle Tier 0 issues if any are available, before moving on to Tier 1 then Tier 2 issues.

> **Note:** For definitions of Tier 1 and Tier 2, see the [MDN documentation priority list](https://mdn-contributor-docs.mozilla.org/legacy/documentation-priorities/).
Generally speaking, critical issues should be fixed immediately, and would probably be handled by MDN staff/peers.

### Provide further information

Expand Down
11 changes: 6 additions & 5 deletions files/en-us/mdn/community/pull_requests/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,10 +125,11 @@ Don't:

- Try to cram multiple fixes into a single pull request. It makes it a lot harder to review, and raises suspicions (some people might think you are trying to hide some malicious code in between the valid changes).

## Opening a pull request
## Deployment timeline

## Reviewing a pull request
After your pull request is merged to [`mdn/content`](https://github.com/mdn/content), it can take up to 48 hours before your changes are live on the [production site](https://developer.mozilla.org/), but it's usually quicker.
The site build runs every 24 hours at around 19:00 US/Eastern time, and is deployed immediately after.
When deploys succeed, it can take up to 24 hours for the CDN to invalidate caches and serve new content.

## Pull requests we accept

## Idle pull requests
For embedded browser compatibility data tables, the [browser-compat-data](https://github.com/mdn/browser-compat-data) project is built and deployed every Tuesday.
You can expect to see merged changes on MDN Web Docs the following Wednesday.
8 changes: 1 addition & 7 deletions files/en-us/mdn/contribute/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,15 +123,9 @@ The links in this section lead to detailed guides explaining how to do a particu

We will add more tasks here as time goes on.

#### Priority ratings

You can also look at priority ratings to give you an idea of what the most important work is to work on — we've started giving content bug issues labels of P0, P1, P2, P3, and P4 to signify how important they are, with lower numbers being more important than higher numbers.

These are figured out during the regular MDN bug triage process, based on the [MDN documentation priority list](https://mdn-contributor-docs.mozilla.org/legacy/documentation-priorities/).

### Other task types

If our main priorities listed above don't interest you, you can find a number of other, more general task types to get involved with below, split up by skillset.
If our main priorities listed above don't interest you, you can find a number of other, more general task types to get involved with below, split up by skill set.

If you are more interested in words, you could do the following:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -49,16 +49,30 @@ The rights in the logos, trademarks, and service marks of the Mozilla Foundation

## Using content from elsewhere on MDN Web Docs

Often, there is useful content about a topic somewhere on the web besides MDN Web Docs. However, copying such content can be fraught with difficulties, both technical and legal.
In general, we do not approve of copying content from other sources and putting it on MDN.
MDN should be made up of original content wherever possible.
If we receive a pull request and discover that it contains plagiarized content, we will close it and request that the submitter resubmit the change with the content rewritten into their own words.

On the technical level, search engines typically penalize a site in their rankings for reproducing content available elsewhere.
Therefore, it is preferable to have original content on MDN Web Docs to enhance the search engine ranking of MDN Web Docs' content.
You can link to the existing content from MDN Web Docs.
### If you want to reuse or republish content

On the legal level, you must be authorized to contribute the content, and it must be licensed and attributed in a way that is compatible with MDN's license.
> **Note:** Unless there is a good reason to republish the content, we will probably say "no".
> The MDN writing team's decision is final.

- **If you created the existing content** (for your own purposes and not as work-for-hire), and you are willing to contribute it to MDN Web Docs under MDN's license, this is the easiest case. You are free to contribute the content.
- **If the copyright for the content belongs to someone else**, it must be licensed and attributed compatibly with MDN's license. It is often not easy for someone who is not a lawyer to determine what licenses are compatible. To be on the safe side, contact a member of the [MDN Web Docs team](https://github.com/mdn/mdn-community/discussions), who may consult Mozilla's Legal team for guidance if necessary.
If someone wants to donate an article to MDN that they previously published on their blog or it makes sense to copy a complex reference sheet to MDN, there may be justification for republishing it. For these cases, discuss your plan with the MDN team beforehand:

- [Create a GitHub issue](https://github.com/mdn/mdn/issues/new/choose) that explains your intention.
- Describe what you would like to copy or republish.
- Provide a URL to the resource.
- Explain why you think it's appropriate.

**If the content is published under a closed license:**

- If you hold the rights to the content, state this and your express agreement to republish it on MDN.
- If you do not hold the rights to the content, include the author/publisher on the issue if possible, or include details of how they could be contacted so we can ask them for permission to republish the content.

**If the content is published under an open license:**

- Say what it is, and link to the license so we can check whether it is compatible with [MDN's license](https://developer.mozilla.org/en-US/docs/MDN/About#using_mdn_web_docs_content).

## Linking to MDN Web Docs articles

Expand Down
69 changes: 67 additions & 2 deletions files/en-us/mdn/writing_guidelines/howto/images_media/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,76 @@ page-type: mdn-writing-guide

{{MDNSidebar}}

## Adding images

To add an image to a document, add your image file to the document's folder, and then reference the image from within the document's `index.md` file using an `<img>` element or [the equivalent Markdown syntax](https://github.github.com/gfm/#images).

Let's walk through an example:

1. Start with a fresh working branch with the latest content from the `main` branch of the `mdn` remote.

```sh
cd ~/path/to/mdn/content
git checkout main
git pull mdn main
# Run "yarn" again just to ensure you've
# installed the latest Yari dependency.
yarn
git checkout -b my-images
```

2. Add your image to the document folder. For this example, let's assume
we're adding a new image to the `files/en-us/web/css` document.

```sh
cd ~/path/to/mdn/content
cp ../some/path/my-cool-image.png files/en-us/web/css/
```

3. Run `filecheck` on each image, which might complain if something's wrong.
For more details, see the [Compressing images](#compressing-images) section.

```sh
yarn filecheck files/en-us/web/css/my-cool-image.png
```

4. Reference your image in the document with an `<img>` element inside `files/en-us/web/css/index.md`:

```html
<img src="my-cool-image.png" alt="My cool image" />
```

5. Add and commit all of the deleted, created, and modified files, as well as
push your branch to your fork:

```sh
git add files/en-us/web/css/my-cool-image.png files/en-us/web/css/index.html
git commit
git push -u origin my-images
```

6. Now you're ready to create your
[pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).

## Compressing images

When you add images to a page on MDN Web Docs, you should make sure that they are compressed as much as possible (without degrading quality) to save on the download size for our readers.
In fact, if you don't do this, our CI process will fail and the build results will warn you that some of your images are too big.

The best way to compress the images is by using the built-in compression tool.
You can compress an image appropriately by using the `filecheck` command with the `--save-compression` option.
This option compresses the image as much as possible and replaces the original with the compressed version.
For example:

```sh
yarn filecheck files/en-us/web/css/my-cool-image.png --save-compression
```

## Adding videos

MDN Web Docs is not a very video-heavy site, but there are certain places where video content makes sense to use as part of an article.
This article discusses when including videos in articles is appropriate and provides tips on how to create simple but effective videos on a budget.

## Using video content

There are several arguments against using video content for technical documentation, particularly for reference material and advanced level guides. Some of these are listed below:

- Video is linear.
Expand Down
5 changes: 5 additions & 0 deletions files/en-us/mdn/writing_guidelines/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,14 @@ MDN Web Docs is an open-source project. The sections outlined below describe our
- [What we write](/en-US/docs/MDN/Writing_guidelines/What_we_write)

- : This section covers what we include on MDN Web Docs and want we don't, as well as a number of other policies, such as when we write about new technologies, the content suggestion process, and whether we accept external links. This is a good place to start if you're considering writing or updating content for us. This section also includes:

- [Inclusion criteria](/en-US/docs/MDN/Writing_guidelines/What_we_write/Criteria_for_inclusion)

- : Provides an in-depth criteria for content to be included on MDN Web Docs, the application process for getting new documentation added on MDN Web Docs, and the expectations and guidelines for a party applying.

- [Content reuse](/en-US/docs/MDN/Writing_guidelines/Content_reuse)
- : Describes our policy on content reuse and republishing, and how to get permission to republish content on MDN Web Docs.

- [Our writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide)

- : The writing style guide covers the language and style we use to write on MDN Web Docs. It also covers how to [format code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide).
Expand Down
Loading