├── .prettierrc.json ├── .gitignore ├── contrib-docs ├── writing-guidelines │ ├── page-structure │ │ ├── macros │ │ │ └── index.md │ │ ├── frontmatter │ │ │ └── index.md │ │ ├── page-types │ │ │ ├── css │ │ │ │ ├── index.md │ │ │ │ └── property │ │ │ │ │ └── index.md │ │ │ ├── html │ │ │ │ └── index.md │ │ │ ├── js │ │ │ │ ├── index.md │ │ │ │ └── errors │ │ │ │ │ └── index.md │ │ │ ├── learn │ │ │ │ └── index.md │ │ │ ├── api │ │ │ │ ├── apiref-links.png │ │ │ │ └── sidebars │ │ │ │ │ └── index.md │ │ │ ├── http │ │ │ │ └── index.md │ │ │ └── glossary │ │ │ │ └── index.md │ │ ├── index.md │ │ ├── updating-json │ │ │ └── index.md │ │ ├── code-examples │ │ │ └── index.md │ │ └── images-media │ │ │ └── index.md │ ├── writing-style-guide │ │ └── code-style-guide │ │ │ ├── shell │ │ │ └── index.md │ │ │ ├── index.md │ │ │ ├── html │ │ │ └── index.md │ │ │ ├── css │ │ │ └── index.md │ │ │ └── javascript │ │ │ └── index.md │ ├── index.md │ ├── attrib-copyright-license │ │ └── index.md │ ├── researching-technology │ │ └── index.md │ ├── creating-moving-archiving-pages │ │ └── index.md │ └── what-we-write │ │ ├── index.md │ │ ├── experimental_deprecated_obsolete │ │ └── index.md │ │ └── inclusion-criteria │ │ └── index.md ├── community-guidelines │ ├── contributing │ │ ├── index.md │ │ ├── getting-started │ │ │ ├── git-github-beginners │ │ │ │ ├── code-popup.png │ │ │ │ ├── new-branch.png │ │ │ │ ├── branch-button.png │ │ │ │ ├── branch-menu.png │ │ │ │ ├── fork-button.png │ │ │ │ ├── open-pull-request.png │ │ │ │ ├── branch-button-new-branch.png │ │ │ │ └── compare-and-pull-request.png │ │ │ └── index.md │ │ ├── our-repositories │ │ │ └── index.md │ │ └── translated-content │ │ │ └── index.md │ ├── mdn-content │ │ ├── issues │ │ │ └── index.md │ │ ├── pull-requests │ │ │ └── index.md │ │ └── index.md │ ├── issues │ │ ├── issue-triage │ │ │ └── index.md │ │ └── index.md │ ├── users-teams │ │ └── index.md │ ├── index.md │ ├── learn-forum │ │ └── index.md │ ├── pull-requests │ │ └── index.md │ └── open-source-etiquette │ │ └── index.md ├── reusables │ ├── section-code-of-conduct.md │ ├── section-get-in-touch.md │ ├── section-trademarks.md │ └── section-open-source.md └── index.md ├── .github └── ISSUE_TEMPLATE │ └── repo-maintenance-.md └── README.md /.prettierrc.json: -------------------------------------------------------------------------------- 1 | {} 2 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/page-structure/macros/index.md: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/page-structure/frontmatter/index.md: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/page-structure/page-types/css/index.md: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/page-structure/page-types/html/index.md: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/page-structure/page-types/js/index.md: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/page-structure/page-types/learn/index.md: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/contributing/index.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | For content specific stuff see... -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/mdn-content/issues/index.md: -------------------------------------------------------------------------------- 1 | # Issues on MDN Content 2 | 3 | TBD -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/issues/issue-triage/index.md: -------------------------------------------------------------------------------- 1 | ## Issue triage 2 | 3 | _(see meta docs)_ -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/mdn-content/pull-requests/index.md: -------------------------------------------------------------------------------- 1 | # Pull request etiquette for MDN Content 2 | 3 | TBD 4 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/page-structure/page-types/api/apiref-links.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdn/content-team-projects/main/contrib-docs/writing-guidelines/page-structure/page-types/api/apiref-links.png -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/contributing/getting-started/git-github-beginners/code-popup.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdn/content-team-projects/main/contrib-docs/community-guidelines/contributing/getting-started/git-github-beginners/code-popup.png -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/contributing/getting-started/git-github-beginners/new-branch.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdn/content-team-projects/main/contrib-docs/community-guidelines/contributing/getting-started/git-github-beginners/new-branch.png -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/contributing/getting-started/git-github-beginners/branch-button.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdn/content-team-projects/main/contrib-docs/community-guidelines/contributing/getting-started/git-github-beginners/branch-button.png -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/contributing/getting-started/git-github-beginners/branch-menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdn/content-team-projects/main/contrib-docs/community-guidelines/contributing/getting-started/git-github-beginners/branch-menu.png -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/contributing/getting-started/git-github-beginners/fork-button.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdn/content-team-projects/main/contrib-docs/community-guidelines/contributing/getting-started/git-github-beginners/fork-button.png -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/contributing/getting-started/git-github-beginners/open-pull-request.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdn/content-team-projects/main/contrib-docs/community-guidelines/contributing/getting-started/git-github-beginners/open-pull-request.png -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/contributing/getting-started/git-github-beginners/branch-button-new-branch.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdn/content-team-projects/main/contrib-docs/community-guidelines/contributing/getting-started/git-github-beginners/branch-button-new-branch.png -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/contributing/getting-started/git-github-beginners/compare-and-pull-request.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdn/content-team-projects/main/contrib-docs/community-guidelines/contributing/getting-started/git-github-beginners/compare-and-pull-request.png -------------------------------------------------------------------------------- /contrib-docs/reusables/section-code-of-conduct.md: -------------------------------------------------------------------------------- 1 | By participating in and contributing to our projects and discussions, you acknowledge that you have read and agree to the [Mozilla community participation guidelines](https://github.com/mdn/mdn-community/blob/main/CODE_OF_CONDUCT.md). 2 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/repo-maintenance-.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 'Repo maintenance ' 3 | about: Checklist for repos 4 | title: '[Repo]' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | - [ ] triage prs 11 | - [ ] triage issues 12 | - [ ] add contribution doc 13 | - [ ] add any notes about repo to readme 14 | - [ ] change master to main 15 | - [ ] move if necessary - create new folder 16 | - [ ] update urls in content 17 | - [ ] archive repo if necessary 18 | - [ ] add to motherboard project 19 | -------------------------------------------------------------------------------- /contrib-docs/reusables/section-get-in-touch.md: -------------------------------------------------------------------------------- 1 | You can communicate with the MDN Web Docs team and community through our [Matrix channel](https://chat.mozilla.org/#/room/#mdn:mozilla.org), forums on [Discourse](https://discourse.mozilla.org/c/mdn/236), and discussions on [GitHub](https://github.com/mdn/mdn-community/discussions). 2 | 3 | - If you are learning web development and are stuck on a coding problem, we have [active forums](https://discourse.mozilla.org/c/mdn/learn/250) where you can ask questions and get help. 4 | -------------------------------------------------------------------------------- /contrib-docs/reusables/section-trademarks.md: -------------------------------------------------------------------------------- 1 | The rights of the trademarks, logos, and service marks of Mozilla and the look and feel of this website are not licensed under the Creative Commons license. Therefore, to the extent they are works of authorship (like logos and graphic design), they are not included in the licensed work under those terms. If you have any other questions about complying with our licensing terms for this collection, you should contact Mozilla here: [licensing@mozilla.org](mailto:licensing@mozilla.org). 2 | -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/users-teams/index.md: -------------------------------------------------------------------------------- 1 | # Users & Teams 2 | 3 | There's lots of different collaborators and partners within the mdn organisation on GitHub. [A list can be found here](https://github.com/orgs/mdn/people). 4 | 5 | 6 | We're currently reviewing the organizations users and teams and will update this page in due course. 7 | 8 | 9 | #### Notes 10 | 11 | Main teams. 12 | 13 | What it means to be in a team 14 | 15 | See translated-content for inspiration 16 | 17 | Content specific - content area pr reviews -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/writing-style-guide/code-style-guide/shell/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Guidelines for styling shell prompt examples 3 | slug: MDN/Guidelines/Code_guidelines/Shell 4 | tags: 5 | - Code 6 | - Guide 7 | - Guidelines 8 | - MDN Meta 9 | - Shell 10 | --- 11 | {{MDNSidebar}} 12 | 13 | A shell is a program that waits for you to type in a command and then press the return key. To indicate which commands you should type, content on MDN Web Docs lists them in a code block, similar to code examples. Such a block looks like this: 14 | 15 | ```bash example-good 16 | # This may take a while... 17 | hg clone https://hg.mozilla.org/mozilla-central/ firefox 18 | cd firefox 19 | ``` 20 | 21 | The following guidelines cover how to write Shell prompt code examples for MDN Web Docs. 22 | 23 | ## General guidelines for shell prompt examples 24 | 25 | When writing a shell code block: 26 | 27 | - Do not include a `$` or `>` at the beginning of a shell instruction. It confuses more than it helps and it is not useful when copying the instructions. 28 | - Comments start with `#`. 29 | - Choose "bash" to indicate the language in markdown. 30 | 31 | ## See also 32 | 33 | [Django server-side development docs](/en-US/docs/Learn/Server-side/Django) show good practice presentation of shell prompt commands. 34 | -------------------------------------------------------------------------------- /contrib-docs/reusables/section-open-source.md: -------------------------------------------------------------------------------- 1 | MDN Web Docs is an open-source, collaborative project that documents web platform technologies, including [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML), [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS), [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript), and [Web APIs](https://developer.mozilla.org/en-US/docs/Web/API). We also provide extensive [learning resources](https://developer.mozilla.org/en-US/docs/Learn) for early-stage developers and students. 2 | 3 | As such, any individual or company can contribute to the content and code of MDN Web Docs. However, it also means that the project needs to comply with the [open source definition](https://opensource.org/osd) and be [governed by an Open Source Initiative(OSI)-approved license](https://opensource.org/licenses). 4 | 5 | At a high level, the open source definition states that the project and its source code should be freely redistributed in part, whole, or part of aggregate software distribution. Being open-source also means that anyone can modify the project and create derivative works. In addition, the project should be free of discrimination against individuals, groups, fields, and endeavors. 6 | 7 | While there are a [number of licenses](https://opensource.org/licenses) that are OSI compliant, MDN Web Docs uses, unless indicated otherwise, a combination of [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/), [MIT](https://opensource.org/licenses/MIT) and the [Mozilla Public License 2.0](https://opensource.org/licenses/MPL-2.0) (MPL-2). Each repository will contain a `LICENSE` detailing the license that governs the specific repository. 8 | 9 | > **NOTE:** The rights of the trademarks, logos, and service marks of Mozilla and the look and feel of this website are not licensed under the Creative Commons license. Therefore, to the extent they are works of authorship (like logos and graphic design), they are not included in the licensed work under those terms. If you have any other questions about complying with our licensing terms for this collection, you should contact Mozilla here: [licensing@mozilla.org](mailto:licensing@mozilla.org). 10 | -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/index.md: -------------------------------------------------------------------------------- 1 | # Community guidelines 2 | 3 | 👋 Welcome to MDN Web Docs on GitHub! MDN Web Docs is an open-source, collaborative project that documents web platform technologies, including [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML), [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS), [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript), and [Web APIs](https://developer.mozilla.org/en-US/docs/Web/API). We also provide extensive [learning resources](https://developer.mozilla.org/en-US/docs/Learn) for early-stage developers and students. 4 | 5 | ## Ways to contribute 6 | 7 | [//]: # "TODO: Remember to update these links as we move the documentation around." 8 | 9 | - [Fixing MDN Web Docs content bugs](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Fixing_MDN_content_bugs) 10 | - [Reviewing MDN Web Docs edits](https://github.com/mdn/content/blob/main/REVIEWING.md) 11 | - [Help beginners to learn on MDN Web Docs](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Help_beginners) 12 | - [Contribute to MDN Web Docs interactive examples](https://github.com/mdn/interactive-examples/blob/main/CONTRIBUTING.md) 13 | - [Help translate MDN Web Docs](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Localize) 14 | - [Help fix known platform issues](https://github.com/mdn/yari/issues) 15 | - [Help us keep browser compatibility data up to date.](https://github.com/mdn/browser-compat-data) 16 | 17 | ## Quick Links 18 | 19 | - [If you are familiar with Git and GitHub](./contributing/getting-started/general/index.md) 20 | - [Get Started with Git and GitHub](./contributing/getting-started/beginners/index.md) 21 | - [Overview of our other repositories](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Where_is_everything) 22 | 23 | ## Code of conduct 24 | 25 | By participating in and contributing to our projects and discussions, you acknowledge that you have read and agree to the [Mozilla community participation guidelines](https://github.com/mdn/mdn-community/blob/main/CODE_OF_CONDUCT.md). 26 | 27 | ## Get in touch 28 | 29 | You can communicate with the MDN Web Docs team and community through our [Matrix channel](https://chat.mozilla.org/#/room/#mdn:mozilla.org), forums on [Discourse](https://discourse.mozilla.org/c/mdn/236), and discussions on [GitHub](https://github.com/mdn/mdn-community/discussions). 30 | 31 | - If you are learning web development and are stuck on a coding problem, we have [active forums](https://discourse.mozilla.org/c/mdn/learn/250) where you can ask questions and get help. 32 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/page-structure/page-types/js/errors/index.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | The MDN [JavaScript error reference](/en-US/docs/Web/JavaScript/Reference/Errors) is a project aiming to help web developers with errors occurring in the [Developer Console](https://firefox-source-docs.mozilla.org/devtools-user/web_console/index.html). You can see this feature in action in Firefox — JavaScript errors contain a "Learn more" link that takes you to the JavaScript error reference containing additional advice for fixing issues. 5 | 6 | In order to help this project, we need to write more error documentation on MDN so that we can add more links to the tools where the messages are thrown. 7 | 8 | ## Prerequisites 9 | 10 | - You will need an [MDN account](/en-US/docs/MDN/Contribute/Getting_started#step_1_create_an_account_on_mdn). 11 | - You will need to know or able to dive into some [JavaScript](/en-US/docs/Web/JavaScript). 12 | 13 | ## Step 1 – find an error to document 14 | 15 | - Firefox/Gecko's error messages: 16 | - Edge/Chakra's error messages: 17 | - Chrome/v8's error messages: 18 | 19 | ## Step 2 – look at existing error docs 20 | 21 | - Look at the existing [JavaScript error reference](/en-US/docs/Web/JavaScript/Reference/Errors) and see how errors are documented. 22 | - Depending on which type of error you want to write about, you can take a closer look at these pages. 23 | - You might want to copy the content of an existing page to kick off your new page. 24 | 25 | ## Step 3 – create a new page 26 | 27 | - All error pages live under this tree: [/docs/Web/JavaScript/Reference/Errors](/en-US/docs/Web/JavaScript/Reference/Errors) 28 | - To create a new page, see the instructions in our [GitHub README](https://github.com/mdn/content#adding-a-new-document). 29 | 30 | ## Step 4 – write some content 31 | 32 | - Either use a copied structure from one of the existing error documents or start from scratch. Your choice! 33 | - You should have at least: 34 | 35 | - A syntax box containing the message as thrown in different browsers. 36 | - The error type. 37 | - A text that explains why this error happened, what its consequences are. Go beyond the thrown message. 38 | - Examples showcasing the error (there might be more than one!) and an example showing how to fix the code. 39 | - Pointers to other reference material on MDN. 40 | 41 | ## Step 5 – get a review 42 | 43 | Once your page is created, submit it as a PR, and a member of our review team will be assigned automatically to review your page. 44 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/page-structure/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Page structure 3 | slug: MDN/Writing_guidelines/Page_structure 4 | page-type: mdn-writing-guide 5 | tags: 6 | - meta 7 | - writing-guide 8 | --- 9 | {{MDNSidebar}} 10 | 11 | This section of MDN Web Docs writing guidelines contains all the information on _how_ our pages are structured: The different types of pages we have, what is included in them, how we use markdown, code example guidelines and more. 12 | 13 | To find out more about _how to contribute_ (which happens through GitHub) please refer to our [community guidelines](). 14 | 15 | > **Note:** All the way through this section we assume you have read the contribution guidelines and are familiar with the mdn/content repository and how to use git and GitHub. 16 | 17 | MDN Web Docs content is primarily held in the mdn/content repository and each page is written in a markdown format with frontmatter information at the top. 18 | 19 | Some content is held in other repositories; primarily code examples (such as interactive examples at the top of pages). Anything related to the platform (the website itself and _not_ the articles) is held within the mdn/yari repository. 20 | 21 | If you're looking for the place to update the browser compatibility tables, that data is held with mdn/browser-compat-data repository. 22 | 23 | ## Editing an existing page 24 | 25 | To edit a page, you need to find the page source in our [content](https://github.com/mdn/content) repo. The easiest way to find it is to navigate to the page you want to edit, go to the bottom of the page, and click on the "Source on GitHub" link. 26 | 27 | For creating, moving, and removing content, please refer to [Creating, moving and deleting pages](/en-US/docs/MDN/Writing_guidelines/Creating_moving_archiving) 28 | 29 | ### Preview changes 30 | 31 | If you are editing the page locally, to see what your changes look like you can go to the content repo folder, execute the CLI command `yarn start`, go to `localhost:5042` in your browser, and navigate to page and view it. Enter the title in the search box to find it easily. The previewed page will update in the browser as you edit the source. 32 | 33 | ### Tags 34 | 35 | You can add or remove tags, which describe the page's content and purpose, in the "tags" list at the top of the page source. See [How to properly tag pages](/en-US/docs/MDN/Contribute/Howto/Tag), for information on which tags to apply. 36 | 37 | ### Attach files 38 | 39 | To attach a file to your article, you just need to include it in the same directory as the article's `index.html` file, and include it in your page, typically via an `` element. 40 | 41 | 42 | ## In this section 43 | 44 | 45 | 46 | ## See also 47 | 48 | - [MDN style guide](/en-US/docs/MDN/Guidelines/Writing_style_guide) 49 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/page-structure/page-types/css/property/index.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | As the [CSS](/en-US/docs/Web/CSS) standards evolve, new properties are always being added. The MDN [CSS Reference](/en-US/docs/Web/CSS/Reference) needs to be kept up-to-date with these developments. This document gives step-by-step instructions for creating a CSS property reference page. 4 | 5 | Each CSS property reference page follows the same structure. This helps readers find information more easily, especially once they are familiar with the standard reference page format. 6 | 7 | ## Step 1 — Decide which property to document 8 | 9 | First, you will need to decide which property to document. You might have noticed that a page is missing, or you might have seen missing content reported in our [issues list](https://github.com/mdn/content/issues). For details about the CSS property you will need to find a relevant specification for it (e.g., a [W3C specification](https://www.w3.org/Style/CSS/), or a bug report for a non-standard property used in rendering engines like Gecko or Blink). 10 | 11 | > **Note:** When using a W3C spec, always use the **Editor's Draft** (note the red banner on the left side) and not a published version (e.g. Working Draft). The Editor's Draft is always closer to the final version! 12 | 13 | If the implementation and spec diverge, feel free to mention it in the implementation bug: it may be a bug in the implementation (and a follow-up bug will be filed), a delay in the publication of a new spec, or an error in the spec (in which case a spec bug is worth filing). 14 | 15 | ## Step 2 — Check the database of CSS properties 16 | 17 | Several characteristics of a CSS property, such as its syntax or if it can be animated, are mentioned in several pages and are therefore stored in an ad-hoc database. Macros that you'll use on the page need information about the property that is stored there, so start by [checking that this information is there](/en-US/docs/MDN/Contribute/Howto/Update_the_CSS_JSON_DB). 18 | 19 | ## Step 3 — Creating the CSS property page 20 | 21 | Preparations finished! Now we can add the actual CSS property page. The easiest way to create a new CSS property page is to copy the content of an existing page and to edit it to suit the new property. You can find out how to add a new page in our [GitHub README](https://github.com/mdn/content#adding-a-new-document). 22 | 23 | When creating a reference page, you'll want to add _Examples_. To do that follow this [tutorial about live samples](/en-US/docs/MDN/Structures/Live_samples). Don't forget that we are in a document explaining one single property: you need to add examples that show how this property is working in isolation, not how the whole specification is used. That means that examples for `list-style-type` should show what the different property values generate, not how to combine it with other properties, pseudo-classes, or pseudo-elements to generate nice effects. Tutorials and guides can be written to show more. 24 | 25 | ## Step 4 — Getting a review 26 | 27 | Once your page is created, submit it as a PR, and a member of our review team will be assigned automatically to review your page. -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: MDN Web Docs writing guidelines 3 | slug: MDN/Writing_guidelines 4 | page-type: mdn-writing-guide 5 | tags: 6 | - meta 7 | - writing-guide 8 | --- 9 | {{MDNSidebar}} 10 | 11 | MDN Web Docs is an open-source project. To find out how to contribute, see our contribution guidelines . 12 | 13 | Here are the guidelines for what we document and how we do it on MDN Web Docs. 14 | 15 | - [What we write](/en_US/docs/MDN/Writing_guidelines/What_we_write) 16 | - : This sections covers what we include on MDN Web Docs and want we don't, as well as a number of policies such as when we write about new technologies, the content suggestion process, whether we accept external links, and when we remove content. This is a good place to start if you're considering writing or updating content for us. This section also includes: 17 | - [Inclusion criteria](/en_US/docs/MDN/Writing_guidelines/What_we_write/Inclusion_criteria) 18 | - : This section provides an in-depth criteria for content to be included on MDN Web Docs, the application process for including new documentation, and expectations and guidelines for a party applying. 19 | 20 | - [Writing style guide](/en_US/docs/MDN/Writing_guidelines/What_we_write) 21 | - : The writing style guide covers the language and style we use to write on MDN Web Docs. 22 | 23 | - [How to write](/en_US/docs/MDN/Writing_guidelines/How_to_write) 24 | - : This section covers all the information for creating and editing pages, including certain processes and techniques we adhere to. This page includes information on getting started, a general overview into how pages are structured, and where to find how-tos on specific tasks. This section also includes: 25 | 26 | - [Moving and deleting pages]() 27 | - : This explains how to move or delete a page. 28 | 29 | - [Researching a technology](/en_US/docs/MDN/Writing_guidelines/Research_technology) 30 | - : This section provides some handy tips for researching a technology you are documenting. 31 | 32 | - [Page types]() 33 | - : Each page on MDN has a specific page type. Whether that's a CSS reference page, or a JavaScript guide page. This section lists the different page types and provides templates for each type. It's a good idea to browse these to understand which page type you are writing. 34 | 35 | - [Markdown]() 36 | - : The markdown format we use derives from [GitHub flavored markdown (GFM)](https://github.github.com/gfm/). This section is a guide to the markdown we use on MDN Web Docs, including formats for specific in-page components, such as notes and definition lists. 37 | 38 | - [Macros]() 39 | - : Macros are shortcuts that are used in pages to generate content, such as sidebars or code examples. This section lists the macros we use and what they do. 40 | 41 | - [Code examples]() 42 | - : There are lots of different ways to include code examples on pages. This section outlines them and provides syntax guidelines for the different languages. 43 | 44 | - [Images and media]() 45 | - : This section describes requirements for including media in pages, such as images. 46 | 47 | - [Attribution and copyright licensing](/en_US/docs/MDN/Writing_guidelines/Attrib_copyright_license) 48 | - : This section describes what copyright license content is and how to attribute correctly. 49 | -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/contributing/our-repositories/index.md: -------------------------------------------------------------------------------- 1 | # Core 2 | 3 | # MDN Core 4 | 5 | [MDN Web Docs](https://developer.mozilla.org) is a complex project with lots of moving parts. It's a good idea to get familiar with the projects different repositories, as there is quite a few bits of the content that aren’t stored in the page sources and instead come from somewhere else. 6 | 7 | This article acts as a quick guide to finding the different repositories (repos) you need to edit to update the different parts of MDN Web Docs content. 8 | 9 | ## Core repos 10 | 11 | - **Core content**: . The most important repo for MDN Web Docs content — this is where all the core English content of the site is stored, and where you'll make all standard changes to page content. 12 | - **MDN Web Docs Platform**: . This is where the MDN Web Docs platform is stored, and where you'll go if you want to make changes to our high level page structure or rendering machinery. 13 | - **Browser compatibility data**: . This is where the data used to generate the browser compatibility tables found on our reference pages is stored ([example](/en-US/docs/Web/HTML/Element/progress#browser_compatibility)). If you have information about browser compatibility of Web features — or are willing and able to do some research and/or experimentation — you can help update MDN's [Browser Compatibility Data](https://github.com/mdn/browser-compat-data/blob/main/docs/contributing.md) 14 | - **Interactive examples**: . This repo stores the example code blocks that are found at the top of many of our reference pages ([example](/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis)). Edit those examples here. 15 | - **Bob** aka Builder of Bits: 16 | This repo stores the rendering code that produce the nice editable, copyable examples found at the top of many of our reference pages ([example](/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis)). 17 | - **Workflows**: 18 | A growing collection of reusable GitHub Actions for use on MDN Web Docs repositories. 19 | - **Translated content**: . This is where localized content lives. Go here if you want to help translate pages into any of our [actively maintained locales](https://github.com/mdn/translated-content#locales). 20 | 21 | 22 | # Code example 23 | 24 | # Code examples and demos 25 | 26 | [//]: # "TODO: UPDATE WITH REPO TRIAGE" 27 | 28 | The MDN Web Docs GitHub org contains a huge number of example repos. These generally contain free-standing code examples that are often linked to from our pages, but occasionally you’ll find one of these examples embedded into a page using a macro call like this — `{{EmbedGHLiveSample("css-examples/learn/tasks/grid/grid1.html", '100%', 700)}}`. 29 | 30 | Always remember, if you are updating the code on any given page, you'll need to update the corresponding example repo as well. 31 | 32 | - **css-examples** [css-examples](https://github.com/mdn/css-examples) ... 33 | - **js-examples** [js-examples](https://github.com/mdn/js-examples) ... 34 | - **html-examples** [html-examples](https://github.com/mdn/html-examples) ... 35 | - **web-audio-examples** [webaudio-examples](https://github.com/mdn/webaudio-examples). 36 | - **web-component-examples** [css-examples](https://github.com/mdn/js-examples) ... 37 | -------------------------------------------------------------------------------- /contrib-docs/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Contributing to MDN Web Docs 3 | slug: MDN/Contribute 4 | page-type: 5 | tags: 6 | - meta 7 | - 8 | --- 9 | {{MDNSidebar}} 10 | 11 | ## MDN Web Docs is open source 12 | 13 | MDN Web Docs is an open-source, collaborative project that documents web platform technologies, including [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML), [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS), [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript), and [Web APIs](https://developer.mozilla.org/en-US/docs/Web/API). We also provide extensive [learning resources](https://developer.mozilla.org/en-US/docs/Learn) for early-stage developers and students. 14 | 15 | As such, any individual or company can contribute to the content and code of MDN Web Docs. However, it also means that the project needs to comply with the [open source definition](https://opensource.org/osd) and be [governed by an Open Source Initiative(OSI)-approved license](https://opensource.org/licenses). 16 | 17 | At a high level, the open source definition states that the project and its source code should be freely redistributed in part, whole, or part of aggregate software distribution. Being open-source also means that anyone can modify the project and create derivative works. In addition, the project should be free of discrimination against individuals, groups, fields, and endeavors. 18 | 19 | While there are a [number of licenses](https://opensource.org/licenses) that are OSI compliant, MDN Web Docs uses, unless indicated otherwise, a combination of [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/), [MIT](https://opensource.org/licenses/MIT) and the [Mozilla Public License 2.0](https://opensource.org/licenses/MPL-2.0) (MPL-2). Each repository will contain a `LICENSE` detailing the license that governs the specific repository. 20 | 21 | > **NOTE:** The rights of the trademarks, logos, and service marks of Mozilla and the look and feel of this website are not licensed under the Creative Commons license. Therefore, to the extent they are works of authorship (like logos and graphic design), they are not included in the licensed work under those terms. If you have any other questions about complying with our licensing terms for this collection, you should contact Mozilla here: [licensing@mozilla.org](mailto:licensing@mozilla.org). 22 | 23 | - [How to write for MDN Web Docs](how-to-write/index.md) 24 | - [Community guidelines](community-guidelines/index.md) 25 | - [Open-source etiquette](community-guidelines/open-source-etiquette/index.md) 26 | 27 | ## Code of conduct 28 | 29 | By participating in and contributing to our projects and discussions, you acknowledge that you have read and agree to the [Mozilla community participation guidelines](https://github.com/mdn/mdn-community/blob/main/CODE_OF_CONDUCT.md). 30 | 31 | ## Get in touch 32 | 33 | You can communicate with the MDN Web Docs team and community using one or more of the following ways: 34 | 35 | - [Matrix channel](https://chat.mozilla.org/#/room/#mdn:mozilla.org) 36 | - Forums on [Discourse](https://discourse.mozilla.org/c/mdn/236). If you are learning web development and are stuck on a coding problem, we have [active forums](https://discourse.mozilla.org/c/mdn/learn/250) where you can ask questions and get help. 37 | - Discussions on [GitHub](https://github.com/mdn/mdn-community/discussions) 38 | 39 | 40 | 41 | MDN Web Docs (previously known as MDN — the Mozilla Developer Network) is an evolving learning platform for Web technologies and the software that powers the Web, including [CSS](/en-US/docs/Web/CSS), [HTML](/en-US/docs/Web/HTML), and [JavaScript](/en-US/docs/Web/JavaScript). We also have a detailed set of beginner's learning material — see [Learn Web development](/en-US/docs/Learn). 42 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | **This repository is archived as of Aug 2022 - you can find current team projects in https://github.com/mdn/mdn** 2 | 3 | # MDN Web Docs Content Team Projects 4 | 5 | This is a holding repo for organising MDN Web Docs team projects & subsequent work. 6 | 7 | This outlines the plan for upcoming & proposed projects for the content team here at MDN. The actual [kanban project can be found here](https://github.com/orgs/mdn/projects/12). The repo will serve as a place to hold outlines and tasks (as issues) that don't pertain to one of the other MDN org repositories directly. 8 | 9 | > We work primarily on GitHub for transparency, and because of the GitHub project feature an associated repository is needed. Eventually this repo will include content suggestions and proposals. For the time being there are held as notes within the main project, or issues within the mdn/content. Please feel free to make suggestions here however, as this will be moved over this year. 10 | 11 | If you have a content or project proposal for the MDN content team, please raise an issue within this repository so we can include it on our roadmap. 12 | 13 | ## Q2 Projects Overview 14 | 15 | Our main projects for Q2 are as follows: 16 | 17 | #### Contribution docs: 18 | We'll be moving the contribution guidelines from the MDN website where they currently are, reviewing/updating them and adding them to our Contribution Handbook website. There are two main areas of this work: 19 | 1. How to write for MDN 20 | 2. How to contribute to MDN 21 | 22 | #### Firefox releases 100 - 102: 23 | We have three Firefox releases for the next quarter and this project will make sure MDN documentation is up to date with the features released 24 | 25 | #### Short surveys: 26 | We'll be running a trial for short surveys on MDN to collect learnings. Once we've proved or dis-proved some assumptions and collected data on what works and what doesn't, we'll look to opening this up for partner input moving forward. 27 | 28 | #### Tidy up demo repos: 29 | We'll be moving some of our smaller demo repositories into our bigger ones (for example violent-theromin into web-audio-examples) as the start of work to reduce the amount of repositories associated with MDN. A clear outcome of this will be to simplify guidelines for contributors and eventually be able to make some bigger decisions around demo code. 30 | 31 | ### Other 32 | 33 | - **Hiring:** We are hiring a full time technical writer, one with a substantial web development backgound. 34 | - **Content Strategy:** We'll be reviewing both MDN and the web platform to define the content work moving forward into the next quarter and beyond. (Note to self include Interop) 35 | - **MDN Content Tools:** We have some internal tools which help to streamline the Firefox releases, see what's upcoming for the web platform and analytics to help us make descisions with regards to our users. We'll be updating and improving these. 36 | 37 | ## Projects on the roadmap past Q2 38 | 39 | Projects we are considering for the rest of the year and possibly beyond. Eventually this will be updated as project outlines within this repository. 40 | 41 | - **General Content:** Post the Content Strategy review above, we'll be outlining content which is needed and content which needs updating. This will be split into individual projects for each part of content work which needs to be done. The planning for this work will happen in Q2 so check back here as this gets expanded and updated. 42 | - **Update page titles:** We'll be updating Web API page titles to a more user friendly format, which includes static vs instance methods. 43 | - **Remove external examples:** We have some examples which are external to the MDN infrastructure. We will look to reducing those and including them, taking ownership, and making it easier to keep them up to date. 44 | 45 | 46 | > This is a new way of working for us, so the format of this repository will change. After each quarter we will update this repository with reviews of work we have done, along side updating with new projects. We will also make changes as per the ongoing work. 47 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/page-structure/page-types/http/index.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | The MDN [HTTP header reference](/en-US/docs/Web/HTTP/Headers) documents HTTP header fields are components of the header section of request and response messages in the Hypertext Transfer Protocol ([HTTP](/en-US/docs/Web/HTTP)). They define the operating parameters of an HTTP transaction. This page explains how to create a new MDN reference page for an HTTP header. 5 | 6 | ## Prerequisites 7 | 8 | - You will need an [MDN account](/en-US/docs/MDN/Contribute/Getting_started#step_1_create_an_account_on_mdn). 9 | - You will need to know or be able to dive into some [HTTP](/en-US/docs/Web/HTTP). 10 | 11 | ## Step 1 – find an HTTP header to document 12 | 13 | - There are many HTTP headers defined in various IETF standards. 14 | - IANA maintains a [registry of headers](https://www.iana.org/assignments/message-headers/message-headers.xhtml) and Wikipedia lists [known header fields](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields), but not all are relevant to web developers or part of an official standard. 15 | - If there are **red links** on the current [MDN header reference overview page](/en-US/docs/Web/HTTP/Headers), these headers are a good choice to document. 16 | - If in doubt, [ask an MDN contributor](/en-US/docs/MDN/Contribute/Getting_started#step_4_ask_for_help) if you are unsure whether or not it makes sense to write about the header you have chosen. 17 | 18 | ## Step 2 – look at existing header reference pages 19 | 20 | - Existing HTTP headers are documented [here](/en-US/docs/Web/HTTP/Headers). 21 | - There are different header categories: {{Glossary("Request header")}}, {{Glossary("Response header")}}, and {{Glossary("Representation header")}}. 22 | - Find the category of the header you are about to document (note that some headers can be both request and response headers, depending on context). 23 | - Go to an existing header reference page that has the same category. 24 | 25 | ## Step 3 – create a new page 26 | 27 | - All header pages live under this tree: [/docs/Web/HTTP/Headers/](/en-US/docs/Web/HTTP/Headers) 28 | - To create a new page, see the instructions in our [GitHub README](https://github.com/mdn/content#adding-a-new-document). 29 | 30 | ## Step 4 – write content 31 | 32 | - Either start from our [template HTTP header page](/en-US/docs/MDN/Structures/Page_types#http_header_reference_page) or use a copied structure from one of the existing HTTP header documents that you found in step 2. It's your choice. 33 | - Write about your new HTTP header. 34 | - Make sure you have these sections: 35 | 36 | - Introductory text where the first sentence mentions the header name (bold) and summarizes its purpose. 37 | - Information box containing at least the header type and if the header is a {{Glossary("Forbidden header name")}}. 38 | - A syntax box containing all possible directives/parameters/values of the HTTP header. 39 | - A section that explains these directives/values. 40 | - An example section that contains a practical use case for this header or shows where and how it occurs usually. 41 | - A specification section listing relevant RFC standard documents. 42 | - A "See also" section listing relevant resources. 43 | 44 | ## Step 4a – add tags to the page 45 | 46 | All HTTP header pages should at least have these tags: "HTTP", "Header", "Reference". 47 | 48 | ## Step 5 – add browser compatibility information 49 | 50 | - If you have looked at other HTTP header pages, you will see that there is a \\{{compat}} macro that will fill in a browser table for you. 51 | - The compatibility table page is generated from structured data. If you'd like to contribute to the data, please check out and send us a pull request. 52 | 53 | ## Step 6 – add the header to the HTTP header list 54 | 55 | - Make sure your header is listed in an appropriate category on the [HTTP header reference overview page](/en-US/docs/Web/HTTP/Headers). 56 | 57 | ## Step 7 – get a review 58 | 59 | Once your page is created, submit it as a PR, and a member of our review team will be assigned automatically to review your page. 60 | -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/mdn-content/index.md: -------------------------------------------------------------------------------- 1 | # Contributing to mdn/content 2 | 3 | Problems with MDN docs are reported as [content repo issues](https://github.com/mdn/content/issues). This article helps you find the _best_ issues to work on, based on your expertise and how much time you have available, and outlines the main steps to fixing them. 4 | 5 | > **Note:** We get a lot of content bugs — any help you can give in fixing them is very much appreciated! 6 | 7 | ## What do we need help with? 8 | 9 | To help you choose what content issues to work on, we've sorted them using GitHub labels. 10 | 11 | The labels below help you find tasks based on how much time you have available. 12 | 13 | | Label | Description | 14 | | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | 15 | | [Less-than-30-minute tasks on the content repo](https://github.com/mdn/content/issues?q=is%3Aissue+is%3Aopen+label%3A%22time%3A+-30mins%22) | A task that will probably take less than 30 minutes. | 16 | | [Less-than-3-hour tasks on the content repo](https://github.com/mdn/content/issues?q=is%3Aissue+is%3Aopen+label%3A%22time%3A+-3hr%22) | A task that will probably take less than 3 hours. | 17 | | [Less-than-2-day tasks on the content repo](https://github.com/mdn/content/issues?q=is%3Aissue+is%3Aopen+label%3A%22time%3A+-2days%22) | A task that will probably take less than 2 days. | 18 | 19 | If you'd prefer to browse your tasks and choose by technology category instead, you can also find content type labels on [issues in the content repository](https://github.com/mdn/content/issues). 20 | 21 | ## How can you benefit? 22 | 23 | - Fixing MDN content bugs is a great way to learn more about web technologies — as you research a problem and create the required content, you will gain a deeper understanding of the subject, and improve your skills. 24 | - As you get more involved in the MDN community, you'll get to know Mozilla staff and other community members, giving you a valuable network of contacts for getting help with your own issues and increasing your visibility. 25 | - Helping to fix problems is largely its own reward, but it will also serve as a record of your open source contributions, demonstrating your expertise in web technologies and possibly even helping you with your course, or job opportunities. 26 | 27 | ## What skills do you need? 28 | 29 | - You need to be knowledgeable in the topic areas that you choose to help with (e.g. JavaScript, CSS). 30 | - Most of the examples and pages that you will help with are written in English, so you should have a reasonable understanding of the English language. But don't worry if your English is not perfect! Our team is more than happy to help clean up any writing. 31 | 32 | ## How to help 33 | 34 | 1. First of all, sign up for a [GitHub account](https://github.com/join), if you don't already have one — you'll need this to communicate on the GitHub issues. 35 | 2. Next, choose one or more topic areas you'd like to help with. Use the list above to get more information to help you make your selection. If you are not sure what a good choice would be, ask for help in the [MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) on [Matrix](https://wiki.mozilla.org/Matrix). 36 | 37 | ### Once you are set up 38 | 39 | 1. Choose an issue to work on that interests you, and ask us to assign it to you with a comment on the issue. 40 | 2. If you need any help when you are working on it, feel free to contact us in the [MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) on [Matrix](https://wiki.mozilla.org/Matrix). 41 | 3. Once you've fixed an issue, ask the submitter for a review and, hopefully, they will tell you whether they think more work is required. We will get involved if needed. 42 | 4. Once the issue is verified fixed, it can be closed. The person closing the issue can be either the original issue submitter, or an MDN staff member. 43 | 44 | > **Note:** When choosing and working on an issue, you might also find our [GitHub best practices](/en-US/docs/MDN/Contribute/GitHub_best_practices) and [Getting started on MDN](/en-US/docs/MDN/Contribute/Getting_started) guides useful. 45 | -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/contributing/translated-content/index.md: -------------------------------------------------------------------------------- 1 | # Localisation 2 | 3 | Since December 14th 2020, MDN has been running on the new GitHub-based [Yari platform](https://github.com/mdn/yari). This has a lot of advantages for MDN, but we've needed to make radical changes to the way in which we handle localization. This is because we've ended up with a lot of unmaintained and out-of-date content in our non-en-US locales, and we want to manage it better in the future. 4 | 5 | We have frozen all localized content (meaning that we won't accept any edits to it; it'll be read-only), EXCEPT for the below locales — these locales have dedicated teams taking responsibility for maintaining them. 6 | 7 | ## Active locales 8 | 9 | > **Note:** If you want to contribute to one of the existing active locales get in touch with one of the active members listed below, or [contact us for help](/en-US/docs/MDN/Contribute/Getting_started#step_4_ask_for_help). 10 | 11 | ### Brazilian Portuguese (pt-BR) 12 | 13 | - Discussions: [Telegram (MDN localization in Brazilian Portuguese)](https://t.me/mdn_l10n_pt_br) 14 | - Current contributors: [Luisa Migueres](https://github.com/lumigueres), [Julio Sampaio](https://github.com/juliosampaio), [Josiel Rocha](https://github.com/josielrocha), [Clóvis Lima Júnior](https://github.com/clovislima) 15 | 16 | ### Chinese (zh-CN, zh-TW) 17 | 18 | - Discussions: [Telegram (MozTW L10n channel)](https://moztw.org/community/telegram/) 19 | - Current contributors: [Irvin](https://github.com/irvin), [t7yang](https://github.com/t7yang), [dibery](https://github.com/dibery) 20 | 21 | ### French (fr) 22 | 23 | - Discussions : [Matrix (#l10n-fr channel)](https://chat.mozilla.org/#/room/#l10n-fr:mozilla.org) 24 | - Current contributors: [cw118](https://github.com/cw118), [Jb Audras](https://github.com/audrasjb), [SphinxKnight](https://github.com/SphinxKnight), [tristantheb](https://github.com/tristantheb) 25 | 26 | ### Japanese (ja) 27 | 28 | - Discussions: [Slack (#translation channel)](https://mozillajp.slack.com/), [GitHub (mozilla-japan)](https://github.com/mozilla-japan/translation), [Google Group (Mozilla.translations.ja)](https://groups.google.com/forum/#!forum/mozilla-translations-ja) 29 | - Current contributors: [mfuji09](https://github.com/mfuji09), [hmatrjp](https://github.com/hmatrjp), [potappo](https://github.com/potappo), [dynamis](https://github.com/dynamis), [kenji-yamasaki](https://github.com/kenji-yamasaki) 30 | 31 | ### Korea (ko) 32 | 33 | - Discussions: [Kakao Talk (#MDN Korea)](https://open.kakao.com/o/gdfG288c) 34 | - Current contributors: [hochan222](https://github.com/hochan222), [yechoi42](https://github.com/yechoi42), [cos18](https://github.com/cos18), [GwangYeol-Im](https://github.com/GwangYeol-Im), [pje1740](https://github.com/pje1740), [nKiNk](https://github.com/nKiNk), [yujo11](https://github.com/yujo11) 35 | 36 | ### Russian (ru) 37 | 38 | - Discussions: [Matrix (#mdn-l10n-ru channel)](https://chat.mozilla.org/#/room/#mdn-l10n-ru:mozilla.org) 39 | - Current contributors: [armanpwnz](https://github.com/armanpwnz), [captainspring](https://github.com/captainspring), [mpstv](https://github.com/mpstv), [myshov](https://github.com/myshov), [Saionaro](https://github.com/Saionaro), [sashasushko](https://github.com/sashasushko), [lex111](https://github.com/lex111) 40 | 41 | ### Spanish (es) 42 | 43 | - Discussions: [Matrix (#mdn-l10n-es channel)](https://chat.mozilla.org/#/room/#mdn-l10n-es:mozilla.org) 44 | - Current maintainers: [@JuanVqz](https://github.com/JuanVqz), [@dacalderonp](https://github.com/dacalderonp), [@lasr21](https://github.com/lasr21), [@tuxxy](https://github.com/tuxxy) 45 | 46 | > **Note:** If you want to discuss unfreezing a currently frozen locale, the [guidelines on what is required can be found here](https://github.com/mdn/translated-content/blob/main/PEERS_GUIDELINES.md#activating-a-locale). 47 | 48 | ## See also 49 | 50 | - [MDN localization update, February 2021](https://hacks.mozilla.org/2021/02/mdn-localization-update-february-2021/) — the latest state of localization on MDN 51 | - [An update on MDN Web Docs' localization strategy](https://hacks.mozilla.org/2020/12/an-update-on-mdn-web-docs-localization-strategy/) — updated strategy based on community feedback 52 | - [MDN Web Docs evolves! Lowdown on the upcoming new platform](https://hacks.mozilla.org/2020/10/mdn-web-docs-evolves-lowdown-on-the-upcoming-new-platform/) — more on the advantages of the new platform, and the rationale behind the localization changes. 53 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/page-structure/page-types/glossary/index.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | This article explains how to add and link to entries in the [MDN Web Docs glossary](/en-US/docs/Glossary). 5 | It also provides guidelines about glossary entry layout and content. 6 | The glossary provides definitions for all the terms, jargon, abbreviations, and acronyms you'll come across when reading MDN content about the web and web development. 7 | 8 | It's possible that the glossary will never be complete because the web is always changing. 9 | By contributing new entries or fixing problems, you can help us update the glossary and fill-in gaps. 10 | 11 | Contributing to the glossary is an easy way to help make the web more understandable for everyone. 12 | You don't need high level technical skills. 13 | Glossary entries are intended to be straightforward and brief. 14 | 15 | ## How to write an entry 16 | 17 | First, choose what topic you'd like to write a glossary entry for. 18 | If you're looking for topics that need a glossary entry, check the [list of undocumented terms](/en-US/docs/Glossary#contribute_to_the_glossary) at the end of the [Glossary landing page](/en-US/docs/Glossary). 19 | 20 | If you have an idea for a new glossary entry, [create a new page](https://github.com/mdn/content#adding-a-new-document) for it underneath the [glossary landing page](https://github.com/mdn/content/tree/main/files/en-us/glossary). 21 | 22 | ### Write a summary 23 | 24 | The first paragraph of any glossary page is a simple and short description of the term. 25 | Preferably, this should be no more than two sentences. 26 | Make sure anyone reading the description can immediately understand the defined term. 27 | 28 | > **Note:** Please don't copy-and-paste from other definitions or content on the internet. 29 | > (And especially not Wikipedia, since its range of license versions is smaller and incompatible with MDN.) Your glossary entry should be original content. 30 | 31 | #### Writing a good glossary entry 32 | 33 | Add a few extra paragraphs if you must, but it's easy to find yourself writing an entire article. 34 | Writing an article is fine, but please don't create it in/for the glossary. 35 | If you aren't sure where to put your article, feel free to [reach out to discuss it](/en-US/docs/MDN/Contribute/Getting_started#step_4_ask_for_help). 36 | 37 | There are a few simple guidelines to consider for writing a better glossary entry: 38 | 39 | - When you use terms in the glossary's description of the term or when you use abbreviation, you should create appropriate links. 40 | Often, this just involves creating links to other pages in the glossary. 41 | - Use appropriate related terms (with links) in the glossary entry, if it can be done without making the article difficult to follow. 42 | Having a good network of related and useful links makes a page—or set of pages—much easier to use. 43 | - Think about the search terms you would choose if you wanted to find this page. 44 | Try to use all the words you would use to search for the term, but without making the glossary entry nonsensical, long, or difficult to read. 45 | 46 | ### Expand with links 47 | 48 | A glossary entry should always end with a _Learn more_ section. 49 | This section should contain links to help the reader move forward: discovering more details; learning to use the relevant technology. 50 | 51 | It is good practice to organize the links into three groups: 52 | 53 | - General knowledge 54 | - : These links provide higher-level information about the term or topic. 55 | For example: a link to a relevant [Wikipedia](https://www.wikipedia.org/) page. 56 | - Technical reference 57 | - : These links offer in-depth technical information, on MDN Web Docs or other sites. 58 | - Learn about it 59 | - : These are links to tutorials, exercises, examples, or any other instructional content that helps the reader learn. 60 | 61 | ## Dealing with disambiguation 62 | 63 | Some terms can have multiple meanings depending upon context. 64 | To resolve ambiguity, follow these guidelines: 65 | 66 | - The term's main page must be a disambiguation page containing the [`GlossaryDisambiguation`](https://github.com/mdn/yari/blob/main/kumascript/macros/GlossaryDisambiguation.ejs) macro. 67 | - The term has subpages that define the term for different contexts. 68 | 69 | Let's illustrate this with an example. 70 | The term _signature_ can have different meanings in at least two different contexts: security and function. 71 | 72 | 1. The page [Glossary/Signature](/en-US/docs/Glossary/Signature) is the disambiguation page with the [`GlossaryDisambiguation`](https://github.com/mdn/yari/blob/main/kumascript/macros/GlossaryDisambiguation.ejs) macro. 73 | 2. The page [Glossary/Signature/Security](/en-US/docs/Glossary/Signature/Security) is the page defining a signature in a security context. 74 | 3. The page [Glossary/Signature/Function](/en-US/docs/Glossary/Signature/Function) is the page defining a function signature. 75 | -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/issues/index.md: -------------------------------------------------------------------------------- 1 | # Issues 2 | 3 | ## Opening an issue 4 | 5 | What info should be included 6 | What we accept and don't accept 7 | 8 | Discussions should be here 9 | 10 | 11 | 12 | ## Make progress, not noise 13 | 14 | Think carefully about the way you handle communication in the project — make sure it is useful, and that it doesn’t make other contributors jobs harder. Submitting pull requests to fix issues is great, but are they truly useful, and easy to review? Filing issues and joining in other conversations is fine, but are your issues and comments on topic, or are they just adding noise? 15 | 16 | As a rule, do: 17 | 18 | - Use [GitHub discussion](https://github.com/mdn/mdn-community/discussions) before filing an issue. This helps to keep issues focused and productive. 19 | - Ask questions using other mechanisms like [chat rooms](https://chat.mozilla.org/#/room/#mdn:mozilla.org) or [forums](<(https://discourse.mozilla.org/c/mdn/236)>) if you are not sure whether something is useful or have a simple question. 20 | - Read the [contributor documentation]() and [how to write documentation]() first to try to solve the issue yourself. 21 | 22 | Don’t: 23 | 24 | - Complicate issues by trying to discuss multiple topics at once, or making off-topic comments. 25 | - Open lots of issues asking vague questions. 26 | - Ask questions without trying to solve the problem yourself first. 27 | 28 | ## Working on an issue 29 | 30 | All repositories have an issue tracker, where you can find tasks to help contribute 31 | 32 | Most repositories have a `help-wanted` label or `good-first-issue` label. Some do not, but this is not a pre-requisite and you are welcome to browse and pick something that is suitable for your skill set. 33 | 34 | Once you've found an issue you'd like to work on, amke sure no one else is assigned to the issue. Add a comment saying you would like to work on it and assign the issue to yourself. 35 | 36 | Most issues need some investigation before work can start, if you need to ask questions 37 | 38 | _(define)_ 39 | 40 | If you take on an issue we expect work to happen in a timely manner. If you can no longer take on the task, leave a comment and unassign yourself. 41 | 42 | Fork and branch the repository, do your work and open a [pull request](linktopullrequest). 43 | 44 | _(more stuff)_ 45 | 46 | Now and then, you may run into problems while using MDN. Whether it's a problem with site infrastructure or an error in documentation content, you can either try to fix it yourself or report the problem. While the former is preferred, the latter is sometimes the best you can manage, and that's okay too. 47 | 48 | The best thing you can possibly do is fix problems you spot yourself — this is done by updating the site source: 49 | 50 | - The MDN content itself is found in the [content](https://github.com/mdn/content) repo. 51 | - The MDN platform code, which renders the content as MDN, is found in the [yari](https://github.com/mdn/yari) repo. 52 | 53 | Both repos include useful information to guide you on how to contribute. 54 | 55 | However, maybe you don't know the answer or are in the middle of a deadline on your own project, and need to jot down the problem so someone can look at it later. 56 | 57 | The way to report a documentation problem by filing an [documentation issue](https://github.com/mdn/content/issues) or [platform issue](https://github.com/mdn/yari/issues), depending on what the problem you've discovered relates to. 58 | 59 | ## When choosing a GitHub issue to work on 60 | 61 | 1. Write a comment in the issue saying that you would like to take it on, and we'll assign you to it. 62 | 63 | - If someone else is already assigned to the issue: 64 | 65 | 1. If this was more than one week ago, and there has not been much activity, @mention them and ask them if you can take it over, or otherwise help get it to completion. 66 | 67 | - If they agree for you to take it, we'll assign you to it and remove them. 68 | - If they agree for you to take it and some work has been done already, or the agreement is to help them out with it, we'll assign you to it alongside them. 69 | 70 | 2. If it was less than one week ago, then have some patience, and give them a chance to work on it. 71 | 72 | 2. If the issue has been marked as complete but needing a review, and you want to review it, @mention them in the comments and say you'll review it. 73 | 74 | ## When you've been assigned to an issue 75 | 76 | 1. Scope out the remainder of the work that needs to be done. 77 | 78 | - If the issue is well-described, and the work is pretty obvious, go ahead and do it. 79 | - If the issue is not well-described, and/or you are not sure what is needed, feel free to @mention the poster and ask for more information. 80 | - If you are not still sure who to ask, ask for help in the [MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) on [Matrix](https://wiki.mozilla.org/Matrix). 81 | 82 | 2. Once you think you've fixed an issue, ask for a review in the comments. 83 | 3. Once an issue has been successfully reviewed and comments answered, you can mark it as closed. 84 | 4. If you no longer have time to work on an issue, let us know in a comment so we can assign it someone else. 85 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/attrib-copyright-license/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Attributions and copyright licensing 3 | slug: MDN/Writing_guidelines/Attrib_copyright_license 4 | page-type: mdn-writing-guide 5 | tags: 6 | - meta 7 | - writing-guide 8 | --- 9 | {{MDNSidebar}} 10 | 11 | ## Using MDN Web Docs content 12 | 13 | MDN Web Doc's content is available free of charge and is available under various open-source licenses. This section covers the types of content we provide and what licenses are in effect for each. 14 | 15 | ### Linking to MDN Web Docs 16 | 17 | We regularly get users asking us questions about how to link to MDN web Docs and whether or not it is even allowed. The short answer is: **yes, you can link to MDN!** Not only is the hypertext link the essence of the Web, it is both a way to point your users to valuable resources as well as a show of trust toward the work our community does. 18 | 19 | ### Documentation and articles 20 | 21 | > **Note:** The content on MDN Web Docs has been prepared with the contributions of authors from both inside and outside Mozilla. Unless otherwise indicated, the content is available under the terms of the [Creative Commons Attribution-ShareAlike license](https://creativecommons.org/licenses/by-sa/2.5/) (CC-BY-SA), v2.5 or any later version. 22 | 23 | Your reuse is published under the same license as the original content—CC-BY-SA v2.5 or any later version. When reusing the content on MDN Web Docs, you need to ensure that attribution is given to the original content as well as to "Mozilla Contributors". Include a hyperlink (online) or URL (in print) to the specific page of the content being sourced. For example, to provide attribution for _this_ article, you can write: 24 | 25 | > [Attributions and copyright licensing](/en_US/docs/MDN/Writing_guidelines/Attrib_copyright_license) by [Mozilla Contributors](/en-US/docs/MDN/About/contributors.txt) is licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/). 26 | 27 | In the above example, "Mozilla Contributors" links to the history of the cited page. See [Best practices for attribution](https://wiki.creativecommons.org/wiki/Marking/Users) for further explanation. 28 | 29 | ### Code samples and snippets 30 | 31 | Code samples added on or after August 20, 2010 are in the [public domain](https://creativecommons.org/publicdomain/zero/1.0/) ([CC0](https://creativecommons.org/publicdomain/zero/1.0/)). No licensing notice is necessary but if you need one, you can use: "Any copyright is dedicated to the Public Domain: https://creativecommons.org/publicdomain/zero/1.0/" 32 | 33 | Code samples added before August 20, 2010 are available under the [MIT license](https://opensource.org/licenses/mit-license.php); you should insert the following attribution information into the MIT template: "© \ \". 34 | 35 | Since the launch of the new Yari MDN platform on December 14 2020, there is currently no way to determine which one you need. We are working on this and will update this content soon. 36 | 37 | ### Contributions 38 | 39 | If you wish to contribute to MDN Web Docs, you agree that your documentation is available under the Attribution-ShareAlike license (or occasionally an alternative license already specified by the page you are editing) and that your code samples are available under [Creative Commons CC-0](https://creativecommons.org/publicdomain/zero/1.0/) (a Public Domain dedication). 40 | 41 | > **Warning:** No new pages may be created using alternate licenses. 42 | 43 | **Copyright for contributed materials remains with the author unless the author assigns it to someone else.** 44 | 45 | If you have any questions or concerns about anything discussed here, please [contact us]() . 46 | 47 | ### Logos, trademarks, service marks and wordmarks 48 | 49 | The rights in the trademarks, logos, and service marks of the Mozilla Foundation, as well as the look and feel of this website, are not licensed under the Creative Commons license, and to the extent they are works of authorship (like logos and graphic design), they are not included in the work that is licensed under those terms. If you use the text of documents, and wish to also use any of these rights, or if you have any other questions about complying with our licensing terms for this collection, you should contact the Mozilla Foundation here: [licensing@mozilla.org](mailto:licensing@mozilla.org "mailto:licensing@mozilla.org"). 50 | 51 | 52 | ## Using content from elsewhere on MDN Web Docs 53 | 54 | Often, there is useful content about a topic somewhere on the web besides MDN Web Docs. 55 | However, copying such content can be fraught with difficulties, both technical and legal. 56 | 57 | On the technical level, search engines typically penalize a site in their rankings for reproducing content available elsewhere. 58 | Therefore, it is preferable to have original content on MDN Web Docs to enhance the search engine ranking of MDN Web Docs' content. 59 | You can link to the existing content from MDN Web Docs. 60 | 61 | 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. 62 | 63 | - **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. 64 | - **If the copyright for the content belongs to someone else**, it must be licensed and attributed compatibly with MDN's license. 65 | It is often not easy for someone who is not a lawyer to determine what licenses are compatible. 66 | 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. 67 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/writing-style-guide/code-style-guide/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Guidelines for styling code examples 3 | slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide 4 | page-type: mdn-writing-guide 5 | tags: 6 | - meta 7 | - writing-guide 8 | --- 9 | {{MDNSidebar}} 10 | 11 | These are guidelines for styling and formatting of code examples and apply to all code, be it HTML, CSS, or JavaScript. For guidelines about what content to include while writing the code examples, see the style guide 12 | 13 | ## Guidelines for formatting 14 | 15 | These guidelines for formatting code examples for MDN Web Docs are also good practices when you are coding. 16 | 17 | ### Indentation 18 | 19 | - Use two spaces per tab for indentation in all code examples. 20 | - Place the open-brace ("`{`") characters on the same line as the statement that opens the block. 21 | 22 | ```html example-good 23 |
24 |

This is my paragraph.

25 |
26 | ``` 27 | 28 | ```js example-good 29 | function myFunc() { 30 | if (thingy) { 31 | console.log('Yup, that worked.'); 32 | } 33 | } 34 | ``` 35 | 36 | ### Spacing 37 | 38 | Add a space between a control statement or loop keyword and its opening parenthesis. 39 | 40 | ```js example-good 41 | if (condition) { 42 | /* handle the condition */ 43 | } else { 44 | /* handle the "else" case */ 45 | } 46 | ``` 47 | 48 | ### Code line length 49 | 50 | - Code lines shouldn't be so long that they require horizontal scrolling to read. 51 | - As a recommended practice, keep code lines up to a maximum of 80 characters long (64 for [interactive examples](https://github.com/mdn/interactive-examples)). 52 | - Break long lines at natural breaking points for the sake of readability, but not at the expense of best practices. 53 | 54 | For example, this is not great: 55 | 56 | ```js example-bad 57 | let tommyCat = 'Said Tommy the Cat as he reeled back to clear whatever foreign matter may have nestled its way into his mighty throat. Many a fat alley rat had met its demise while staring point blank down the cavernous barrel of this awesome prowling machine.'; 58 | ``` 59 | 60 | This is better, but somewhat awkward: 61 | 62 | ```js 63 | let tommyCat = 'Said Tommy the Cat as he reeled back to clear whatever foreign ' 64 | + 'matter may have nestled its way into his mighty throat. Many a fat alley rat ' 65 | + 'had met its demise while staring point blank down the cavernous barrel of ' 66 | + 'this awesome prowling machine.'; 67 | ``` 68 | 69 | Even better is to use a template literal: 70 | 71 | ```js example-good 72 | let tommyCat = `Said Tommy the Cat as he reeled back to clear whatever foreign 73 | matter may have nestled its way into his mighty throat. Many a fat alley rat 74 | had met its demise while staring point blank down the cavernous barrel of 75 | this awesome prowling machine.`; 76 | ``` 77 | 78 | ```js example-good 79 | if (class.CONDITION || class.OTHER_CONDITION || class.SOME_OTHER_CONDITION 80 | || class.YET_ANOTHER_CONDITION ) { 81 | /* something */ 82 | } 83 | 84 | var toolkitProfileService = Components.classes["@mozilla.org/toolkit/profile-service;1"] 85 | .createInstance(Components.interfaces.nsIToolkitProfileService); 86 | ``` 87 | 88 | ### Code block height 89 | 90 | Code blocks should be as long as they need to be, but no longer. Ideally, aim for something short like 15-25 lines. If a code block is going to be a lot longer, consider just showing the most useful snippet, and link to the full example on a GitHub repo or codepen, say. 91 | 92 | #### Inline code formatting 93 | 94 | Use the {{HTMLElement("code")}} tags to mark up function names, variable names, and method names. 95 | For example: "the `frenchText()` function". 96 | 97 | **Method names should be followed by a pair of parentheses.** For example, `doSomethingUseful()`. 98 | The parentheses help differentiate methods from other code terms. 99 | 100 | ## Guidelines for proper rendering 101 | 102 | These guidelines should be followed to ensure that the code examples you write display properly on MDN Web Docs. You should also consider responsiveness making writing code examples so that they are also useful on mobile devices. 103 | 104 | ### Size of the rendered code example 105 | 106 | - **Set the width to 100%**: The main content pane on MDN Web Docs is about 700px wide on desktop, so the embedded code examples must look OK at that width. 107 | - **Set height below 700px**: We recommend keeping this height for the rendered code example width for maximum onscreen legibility. 108 | 109 | ### Color in the rendered code example 110 | 111 | - Use keywords for primary and other "basic" colors, for example: 112 | 113 | ```css example-good 114 | color: black; 115 | color: white; 116 | color: red; 117 | ``` 118 | 119 | - Use `rgb()` for more complex colors (including semi-transparent ones): 120 | 121 | ```css example-good 122 | color: rgb(0, 0, 0, 0.5); 123 | color: rgb(248, 242, 230); 124 | ``` 125 | 126 | - If you have to use hex colors, then use lower-case: 127 | 128 | ```css example-good 129 | color: #058ed9; 130 | color: #a39a92; 131 | ``` 132 | 133 | - Use the short form where relevant: 134 | 135 | ```css example-good 136 | color: #ff0; 137 | color: #fff; 138 | ``` 139 | 140 | ### Mark rendered examples as good or bad 141 | 142 | You'll notice on this page that the code blocks that represent good practices to follow are rendered with a green check mark in the right corner, and the code blocks that demonstrate bad practices are rendered with white cross in red circle. 143 | 144 | You can follow the same style while writing code examples. You don't need to use this style everywhere — only on pages where you want to specifically call out good and bad practices in your code examples. 145 | 146 | To get this rendering, use "code fences" to demarcate the code block, followed by the language info string. For example: 147 | 148 | ```js 149 | function myFunc() { 150 | console.log('Hello!'); 151 | }; 152 | ``` 153 | 154 | To represent the code block as a good or bad example, add `example-good` or `example-bad` after the language string, like so: 155 | 156 | ````plain 157 | ```html example-good 158 |

159 | ``` 160 | 161 | ```html example-bad 162 |

163 | ``` 164 | ```` 165 | 166 | These will be rendered as: 167 | 168 | ```html example-good 169 |

170 | ``` 171 | 172 | ```html example-bad 173 |

174 | ``` 175 | -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/contributing/getting-started/index.md: -------------------------------------------------------------------------------- 1 | # Getting Started 2 | 3 | MDN Web Docs needs your help. This page outlines what you can do to help. 4 | 5 | > **Note:** If you haven't contributed to MDN previously, the [Getting Started](general/index.md) guide explains the process in four simple steps. Good news, you're already on step 2: "Picking a task to complete."! 6 | 7 | ## What can I do to help? 8 | 9 | There are multiple avenues you can take to contribute to MDN depending on your skillset and interests. Along with each task we provide a short description and an approximate time that each type of task typically takes. 10 | 11 | If you are not sure what to do, you are always welcome to [ask for help](general/index.md#step_4_ask_for_help). 12 | 13 | ## Primary contribution types 14 | 15 | The links in this section lead to detailed guides explaining how to do a particular contribution task that we are most interested in getting community help with, either because they are a critical function, and/or because they have a large backlog associated with them. Please consider helping out with these tasks before you consider contributing in other ways. 16 | 17 | ### Fixing content bugs 18 | 19 | Our [content repo](https://github.com/mdn/content/) is where people [submit issues](https://github.com/mdn/content/issues) to report problems found with MDN docs. We get a lot of content bugs, and any help you can give in fixing them would be much appreciated. 20 | 21 | #### Skillset required 22 | 23 | - Basic knowledge of using [Git and GitHub](../getting-started/git-github-beginners/index.md). 24 | - Knowledge of the web technologies you choose to help with (e.g JavaScript, CSS). 25 | - A reasonable understanding of the English language (don’t worry if your English is not perfect; we can help you with it). 26 | 27 | ### Reviewing content pull requests 28 | 29 | People submit pull requests on our content repo all the time to update MDN content, and we need help reviewing them. Read our pull request review guide to find out how the reviewing process works, and how you can get involved. 30 | 31 | #### Skillset required 32 | 33 | - Basic knowledge of using [Git and GitHub](../getting-started/git-github-beginners/index.md). 34 | - Knowledge of the web technologies you choose to help with (e.g JavaScript, CSS). 35 | - A reasonable understanding of the English language (don’t worry if your English is not perfect; we can help you with it). 36 | 37 | ## Repositories 38 | 39 | The documentation you read on MDN Web Docs is made up of an array of sources all of which can be found on GitHub. 40 | 41 | - [MDN Core](../repositories/core-repositories/index.md) 42 | - [Code examples and demos](../repositories/code-examples-demos/index.md) 43 | 44 | ## How MDN works 45 | 46 | Intro to content, yari, kuma, bcd, interactive examples etc... 47 | 48 | The best way to get started is by finding an issue to fix on one of our repositories 49 | 50 | # Getting started with MDN Web Docs 51 | 52 | We are an open community of developers building resources for a better Web, regardless of brand, browser, or platform. Anyone can contribute, and each person who does contribute makes us stronger. Together we can continue to drive innovation on the Web to serve the greater good. It starts here, with you. 53 | 54 | Every part of MDN (docs, demos, and the site itself) is created by an open community of developers. Please, join us! 55 | 56 | ## 4 simple steps to MDN 57 | 58 | MDN is an open source resource where **anyone** can add and edit content. You don't need to be a programmer or know a lot about technologies. There are plenty of things that need to be done, from proofreading and correcting typos to writing API documentation. 59 | 60 | Contributing is easy and safe. Even if you make a mistake, it's easily fixed. Even if you don't know exactly how things should look, or your grammar isn't all that good, don't worry about it! We have a team of people whose job it is to make sure that MDN's contents are as good as possible. Someone will be along to make sure your work is tidy and well-written. Share what you know and follow your strengths. 61 | 62 | ### Step 1: Create a GitHub account 63 | 64 | To begin your contributions to MDN, you need to [create a GitHub account](https://github.com/mdn/content/#setup). 65 | 66 | ### Step 2: Pick a task to complete 67 | 68 | Now that you are logged in, read the descriptions of the different task types available on the [main Contribute page](../../index.md#ways-to-contribute), and decide which one most appeals to you. You can pick any task you like and begin your contribution. 69 | 70 | ### Step 3: Do the task 71 | 72 | Once you've decided what kind of task you want to do, find a specific page, code example, etc. to work on, and just do it! 73 | 74 | ### Step 4: Ask for help 75 | 76 | If you are not sure what to do at any point, then you are more than [welcome to ask for help](../../index.md#get-in-touch). Don’t worry about doing it perfectly; other MDN Web Docs contributors are here to help fix errors that slip through. 77 | 78 | ## Useful beginner's guides 79 | 80 | We expect contributors to MDN to have a certain amount of prerequisite knowledge 81 | before they start contributing to the content. If you are new to the following 82 | topics, we'd advise you to look at the provided links to help you get up to 83 | speed: 84 | 85 | - Web technologies: If you are new to HTML, CSS, JavaScript, etc., check out our [Learn web development](/en-US/docs/Learn) tutorials. 86 | - Open source: If you've never contributed to an open source project before, have a read of [Basic etiquette for open source projects](/en-US/docs/MDN/Contribute/Open_source_etiquette). 87 | - Git and GitHub: If you are unfamiliar with these tools, [GitHub for complete beginners](/en-US/docs/MDN/Contribute/GitHub_beginners) will get you started. 88 | - MDN's repo structures: If you are not sure what repos to edit to make changes to the different parts of MDN's content, [Where is everything on MDN?](/en-US/docs/MDN/Contribute/Where_is_everything) will point you towards the correct places. 89 | 90 | 91 | ### Contributions 92 | 93 | When contributing, you must make your contributions available under the Attribution-ShareAlike license (or an alternative license already specified by the page you are editing). In addition, code samples are available under [Creative Commons CC-0](https://creativecommons.org/publicdomain/zero/1.0/) (a Public Domain dedication). By contributing, you agree that your contributions will be available under those licenses. 94 | 95 | > **NOTE:** No new pages may be created using a license other than CC-BY-SA v2.5. 96 | 97 | **Copyright for contributed materials remains with the author unless the author assigns it to someone else**. 98 | 99 | If you have any questions or concerns about anything discussed here, please [open a discussion](https://github.com/mdn/mdn-community/discussions/categories/content) and let us know. 100 | 101 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/researching-technology/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Researching a technology 3 | slug: MDN/Writing_guidelines/Research_technology 4 | page-type: mdn-writing-guide 5 | tags: 6 | - meta 7 | - writing-guide 8 | --- 9 | {{MDNSidebar}} 10 | 11 | This guide gives you some handy information about approaching how to document technologies. 12 | 13 | ## Getting prepared 14 | 15 | Before starting to document or update something on MDN, there are some things you should prepare and plan in advance of starting to actually write. 16 | 17 | It is assumed that before reading this guide you have a reasonable knowledge of: 18 | 19 | - Web technologies like HTML, CSS and JavaScript. 20 | - Reading Web technology specs. You'll be looking at these a lot as you document APIs. 21 | 22 | Everything else can be learned along the way. 23 | 24 | ### Resources 25 | 26 | Useful resources for any of the documentation include: 27 | 28 | 1. The 'How To Write' docs for MDN. You're already here, but it's good to browse through all the docs and familiarize yourself with our writing style, the different types of pages and what sections are included in them, and the different ways we include different parts of the page (like specifications and browser compatibility). 29 | 2. The latest spec: 30 | Different standards bodies create specifications for technologies documented on MDN. For example TC39 for JavaScript, or the W3C for HTML, CSS and Web APIs. 31 | Specs are linked to from reference pages on MDN (check the 'Specifications' section). Alternatively, you can usually do a Web search. Always work from the latest, most up to date specification. 32 | 3. The latest modern web browsers: 33 | These should be experimental/alpha builds such as [Firefox Nightly](https://www.mozilla.org/en-US/firefox/channel/desktop/)/[Chrome Canary](https://www.google.com/intl/en/chrome/canary/) that are more likely to support the features you are documenting. 34 | This is especially pertinent if you are documenting a feature which is 'upcoming'. 35 | 4. Demos/blog posts/other info: Find as much info as you can. If you are updating a technology because it has changed, you need to be careful existing resources you are using to learn are not out of date. This is why the first two points above are important. 36 | 37 | It can also be wise to try and find someone to help answer questions. This can be the specification authors, or the engineers who implement browser features. 38 | 39 | ### Reading specifications 40 | 41 | This can feel a little alien to start, but the more you do it the more you get used to it. Here are some good links to help you get started: 42 | 43 | - [How to read W3C specs](https://alistapart.com/article/readspec/) by J. David Eisenberg on A List Apart 44 | - [Understanding the CSS Specifications](https://www.w3.org/Style/CSS/read) from the w3c 45 | - [How to read web specs Part I – Or: WebVR, how do you work?](https://surma.dev/things/reading-specs/) talks through reading the WebVR spec specifically, but is a great introduction to reading Web API specs. 46 | - [How to read web specs Part IIa – Or: ECMAScript Symbols](https://surma.dev/things/reading-specs-2/) the second part to the link above contains information on understanding the ECMAScript specification which outlines the JavaScript language 47 | 48 | In addition we have a guide on [Information contained in a WebIDL file]() which can really help when reading Web API specs. 49 | 50 | ## Take some time to play with the feature 51 | 52 | You will return to writing code examples or building demos many times through the course of documenting a technology, but it is very useful to start by spending time familiarizing yourself with how the technology works. This is a really valuable exercise, as it gives you a good understanding of what the use cases are (_why_ a developer would use this technology) and help with creating some example code at the same time. 53 | 54 | 55 | > **Note:** If the spec has been recently updated so that, say, a method is now defined differently, but the old method still works in browsers, you will often have to document both in the same place, so that the old and new methods are covered. 56 | > If you need help, refer to demos you have found, or ask an engineering contact. 57 | 58 | ## Create the list of documents you need to write or update 59 | 60 | The different pages you need to write or modify varies depending on the technology you are writing about. Check out the [Page types]() and the relevant section for the technology you're documenting. You'll most likely need to update existing documentation as well, so search MDN for pages which are related to what you are writing about. 61 | 62 | ### Sidebars 63 | 64 | It's possible the sidebar of the pages you write also need to be defined or updated. To find out if this is needed and how to do it [check out our sidebar guide](). 65 | 66 | ### Code examples 67 | 68 | Some of the code examples for MDN docs are held in separate repositories (most notably interactive examples at the top of pages and larger demo code needed for guides). You can find a handy [list of them here]() to find which one you should add to. If you do need to add to or amend one of these repos, it's a good idea to make a note of it in your list. 69 | 70 | ### Example 71 | 72 | Let's say you're documenting a new Web API, your initial list will look a little something like this: 73 | 74 | 1. Overview page 75 | 2. Interface pages 76 | 3. Constructor pages 77 | 4. Method pages 78 | 5. Property pages 79 | 6. Event pages 80 | 7. Concept/guide pages 81 | 8. Code examples 82 | 9. Sidebars 83 | 84 | You can then expand on it with more details, adding each interface and it's members. For examples if you were documenting the Web Audio API, your list might look something more like this: 85 | 86 | 87 | - Web_Audio_API 88 | - AudioContext 89 | 90 | - AudioContext.currentTime 91 | - AudioContext.destination 92 | - AudioContext.listener 93 | - ... 94 | - AudioContext.createBuffer() 95 | - AudioContext.createBufferSource() 96 | - ... 97 | 98 | - AudioNode 99 | 100 | - AudioNode.context 101 | - AudioNode.numberOfInputs 102 | - AudioNode.numberOfOutputs 103 | - ... 104 | - AudioNode.connect(Param) 105 | - ... 106 | 107 | - AudioParam 108 | - Events (update list) 109 | 110 | - start 111 | - end 112 | - … 113 | 114 | 115 | ### Open an issue 116 | 117 | It's a good idea at this point to open a tracking issue on mdn/content with the pages listed as a todo (checkbox) list. This enables not just you, but others working on documentation to publicly keep track of the status. You can also link your pull requests to this issue to give them more context. 118 | 119 | ## Create the pages 120 | 121 | Now create the pages you need, according to the structures below. Our [MDN content README](https://github.com/mdn/content#adding-a-new-document) contains instructions on creating a new document, and our [Page types](/en-US/docs/MDN/Structures/Page_types) guide contains further examples and page templates that might be useful. 122 | 123 | 124 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/page-structure/updating-json/index.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | MDN stores data in well-defined structures when possible. This information is then centralized and can be updated once, while being used in numerous places. 4 | 5 | There are several such files, and this document describes their purpose, structure, and maintenance process. 6 | 7 | ## GroupData: logical grouping of APIs 8 | 9 | `GroupData` is a JSON file collecting information about Web APIs. The grouping of APIs is somewhat fuzzy: any interface, method or property can be part of several APIs. The set of APIs grouped under a name is a convention used to communicate about a feature, without any technical enforcement. 10 | 11 | Yet, MDN needs this information to create coherent Web-API sidebars (like with the `\{{APIRef}}` macro) with the proper reference pages, guides, and overview articles. 12 | 13 | GroupData does exactly that: for each API, it lists the interfaces, properties, methods, guides, and overview pages. In the past, it also listed dictionaries and callbacks. But that use, though still supported, is deprecated and will be removed in the future. 14 | 15 | ### Structure of GroupData 16 | 17 | > **Warning:** Non-existent pages listed in this file are ignored (in en-US). 18 | 19 | An entry in `GroupData.json` has the following structure: 20 | 21 | ```json 22 | "Name_of_the_API": { 23 | "overview": ["name_of_the_overview_page"], 24 | "guides": [ 25 | "name_of_guide_1", 26 | (…) 27 | ], 28 | "interfaces": [ 29 | "name_of_interface_1", 30 | (…) 31 | ], 32 | "methods": [ 33 | "name_of_additional_method_1", 34 | (…) 35 | ], 36 | "properties": [ 37 | "name_of_additional_property_1", 38 | (…) 39 | ], 40 | "events": [ 41 | "name_of_additional_property_1", 42 | (…) 43 | ] 44 | } 45 | ``` 46 | 47 | …where: 48 | 49 | - `"Name_of_the_API"` 50 | - : This key is both an ID used by sidebar macros like `\{{APIRef("Name_of_the_API")}}` and the name displayed in the sidebar itself. Choose it wisely. 51 | > **Warning:** If you want to change the name displayed in the sidebar, you must edit all the pages displaying it. 52 | - `"overview"` 53 | - : This is a list containing one page: the overview page, used as the link for the `"Name_of_the_API"` text. The value is the _title of the page_, and the page must be in the `web/api/`directory. 54 | - `"guides"` 55 | - : This is a list of guides to display in the sidebar, in the given order. The values are _paths to the page_, starting with `/docs/`. 56 | - `"interfaces"` 57 | - : This lists the interfaces that are part of the API. 58 | - `"methods"` 59 | - : This lists the methods that are part of the API. 60 | > **Note:** The methods of the interfaces listed in `"interfaces"` **must** not be listed there. They are automatically added to the sidebar if the tag `Method` is in the YAML header on that page. 61 | - `"properties"` 62 | - : This lists the methods on other interfaces that are part of the API, like `navigator.xr` (a property that the WebXR API adds to the `navigator` object) 63 | > **Note:** The properties of the interfaces listed in `"interfaces"` **must** not be listed there. They are automatically added to the sidebar if the tag `Property` is in the YAML header on that page. 64 | - `"events"` 65 | - : This lists events of other interfaces that are part of the API. The values are the _title of the pages_ (that must reside under `Web/Events`) 66 | > **Note:** The events targeting the interfaces listed in `"interfaces"` **must** not be listed there. They are automatically added to the sidebar if the tag `Event` (singular!) is in the YAML header on that page. 67 | 68 | There are two other keys, `"dictionaries"` and `"callbacks"`, operating on the same principle. As we no longer document these entities in their own pages, their use is deprecated, and no new entry should be added to them (and we remove them little by little). 69 | 70 | > **Note:** Also, none of the keys are mandatory; it is good practice (and we'll enforce this) to add the non-deprecated ones with an empty list rather than omitting them. It shows that the absence of value is a conscious choice. 71 | 72 | ### Update process for GroupData 73 | 74 | This file should be updated in the same PR where changes affecting the sidebar happens. That way, the sidebar is always up-to-date. Reviewers shouldn't merge PRs that don't adopt it. 75 | 76 | To test your changes, check that the sidebar in the files in your PR displays all entries correctly. 77 | 78 | The `GroupData.json` file is located [here](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) on GitHub. 79 | 80 | ## InterfaceData: recording interface inheritance 81 | 82 | > **Note:** We hope to generate this file automatically from the data available via w3c/webref in the future. 83 | 84 | `InterfaceData` describes the hierarchy of the interfaces. It lists inheritance. In the past, it also listed mixins implemented by each interface; but that usage is deprecated, and we remove mixins from this file at the same rate MDN is updated. 85 | 86 | This inheritance data is used when building API sidebars and by the `\{{InheritanceDiagram}}` in the interface pages. 87 | 88 | ### Structure of InterfaceData 89 | 90 | An entry in `InterfaceData.json` has the following structure: 91 | 92 | ```json 93 | "Name_of_the_interface": { 94 | "inh": "Name_of_the_parent_interface", 95 | "impl": [] 96 | } 97 | ``` 98 | 99 | > **Note:** As mixins are deprecated, `"impl"` must be an empty list for all new interfaces. 100 | 101 | The value of `"Name_of_the_parent_interface"` is not a list but a single entry, mandatory; we must not list any interface that don't inherit from another one. 102 | 103 | ### Update process for InterfaceData 104 | 105 | The same PR adding a new interface that inherits from another one must update this file. Reviewers shouldn't merge PRs that don't do so. 106 | 107 | To test your changes, check that the sidebars of each interface you edited in your PR display inheritance correctly. 108 | 109 | The `InterfaceData.json` file is located [here](https://github.com/mdn/content/blob/main/files/jsondata/InterfaceData.json) on GitHub. 110 | 111 | ## SpecData: Specification information 112 | 113 | > **Warning:** The `SpecData.json` file is no longer maintained. Canonical specification information is stored at w3c/browser-spec and in the `spec_url` key of features at mdn/browser-compat-data. 114 | 115 | The `\{{SpecName}}` and `\{{Spec2}}` macros that we are removing use the `SpecData.json` file. We do not accept any further contributions to the `SpecData.json` file; instead, either try to insert a specification table, using the `\{{Specifications}}` macro, or try to hardcode the (good) link to the specification. Note that most of the time, mentioning or linking to a specification outside the _Specifications_ section is a sign of something not appropriately documented on MDN. 116 | 117 | The `SpecData.json` file is located [here](https://github.com/mdn/content/blob/main/files/jsondata/SpecData.json) on GitHub. 118 | -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/learn-forum/index.md: -------------------------------------------------------------------------------- 1 | # Learn Forum 2 | 3 | Our [Learn web development](/en-US/docs/Learn) pages get over a million views per month, and have [active forums](https://discourse.mozilla.org/c/mdn/learn/250) where people go to ask for general help, or request that their assessments be marked. We'd love some help with answering posts, and growing our learning community. 4 | 5 | ## What do we need help with? 6 | 7 | In the [MDN learning forum](https://discourse.mozilla.org/c/mdn/learn/250), there are two main types of post that we'd like you to help out with answering: 8 | 9 | 1. General questions about web development. 10 | 2. Specific questions asking for help or assessment with the skill tests and assessments that appear on the Learn web development section on MDN. 11 | 12 | ## How can you benefit? 13 | 14 | - Helping people with their code problems is a great way to learn more about web technologies — as you research a solution and write an answer to someone's question, you will gain a deeper understanding of the subject, and improve your skills. 15 | - As you get more involved in the MDN community, you'll get to know Mozilla staff and other community members, giving you a valuable network of contacts for getting help with your own issues and increasing your visibility. 16 | - Helping to answer coding questions is largely its own reward, but it will also demonstrate your expertise in web technologies and possibly even help you with your course, or job opportunities. 17 | 18 | ## What skills do you need? 19 | 20 | - You should be knowledgeable in web technologies such as HTML, CSS, and JavaScript. Ideally you should also be good at explaining technical topics, and enjoy helping beginners learn to code. 21 | - The language of the forum is English — you should have a reasonable proficiency with the English language, but it really doesn't need to be perfect. We have people from all over the world visiting our forums, and we want everyone who visits us to feel as comfortable and included as possible. 22 | 23 | ## How to help 24 | 25 | 1. First of all, [sign up for an MDN account](/en-US/docs/MDN/Contribute/Getting_started#step_1_create_an_account_on_mdn), if you don't already have one. You don't absolutely need to do this to help in the learning area, but it will be useful in the long run. 26 | 2. Also sign up for [Mozilla Discourse](https://discourse.mozilla.org/), if you haven't already. 27 | 3. Have a look at [Learn web development](/en-US/docs/Learn) section and gain a basic level of familiarity with what's there, if you haven't already (see the [Structure of the MDN Learning Area](#structure_of_the_mdn_learning_area) section below for help). 28 | 29 | ### Once you are set up 30 | 31 | 1. Have a look at the [learning forum](https://discourse.mozilla.org/c/mdn/learn/250) and see if there are any posts that have no replies — this is the best place to start. 32 | 33 | - Hint: If you can't find any that have no replies, check some of the other ones that were recently updated and see if you can add anything useful that has not already been said. 34 | 35 | 2. If the post you are replying to is a general ask for help, reply to them, and give them as much help as you've got time for. 36 | 3. If the post you are replying to is requesting an assessment for one of the "test your skill"/"assessment" tasks: 37 | 38 | 1. Identify which article/task is being assessed, and find the associated marking guide for it. It is totally OK to ask the person who submitted the post if they can give you the link to the assessment/skill test. 39 | 2. Identify the person's code — they should give it to you in the form of a codepen/jsfiddle/jsbin link, or similar. If they don't provide it in a form that is easy to assess, it is perfectly OK to ask them to put it in codepen, jsfiddle, or similar. 40 | 41 | - A common problem is when people post their code directly into a discourse message — discourse renders HTML elements and turns quotes into smartquotes, which breaks code. It is much better to get it sent over as a URL to a shareable code editor app. 42 | 43 | 3. Read through the code and assess it 44 | 45 | 1. Does it work, and does it give you the result that it should give? 46 | 2. If not, why doesn't it work? 47 | 3. Are there any tips you can give the person to make the code better (more efficient, best practice, etc.)? 48 | 49 | 4. Give them a report on how they did: 50 | 51 | 1. Some of the marking guides suggest a marking scheme with points for each bit of the question, but you don't need to be that accurate. 52 | 2. If the person did great except for a few nitpicks, tell them the nitpicks, but give them lots of praise too. 53 | 3. If the person was nearly there but it wasn't quite right, tell them they did great, but then share the fixes they'd need to make it work, and perhaps even link to the marking guide so they can see what we did. 54 | 4. If the person is not really anywhere near a working solution, be kind and encouraging and try to give them a few clues as to what direction they should go in. Give them another chance to try to do it better. 55 | 5. If you need assistance with anything, ask for help in the [MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) on [Matrix](https://wiki.mozilla.org/Matrix). 56 | 57 | > **Note:** Important: Above all, be patient, be friendly, be kind. Remember — most of these folks are beginners. 58 | 59 | ## Structure of the MDN Learning Area 60 | 61 | When helping answer questions related to the [Learn web development](/en-US/docs/Learn) section of MDN, it is a good idea to have a look around it and gain a basic level of familiarity with what's there. 62 | 63 | 1. Have a look through the page structure in general. 64 | 2. Especially look at the types of assessments available, 65 | 66 | - from the numerous "test your skills" articles available (e.g. see [/en-US/docs/Learn/JavaScript/Building_blocks/conditionals#Test_your_skills!](/en-US/docs/Learn/JavaScript/Building_blocks/conditionals#test_your_skills!)) 67 | - to the more in-depth assessments at the end of some modules (e.g. see [/en-US/docs/Learn/JavaScript/Building_blocks/Image_gallery](/en-US/docs/Learn/JavaScript/Building_blocks/Image_gallery)) 68 | 69 | 3. Have a look at the GitHub repos associated with the learning area (most of the files are available in , some are in ). Most of the examples learners will want help with are contained here. 70 | 4. Each assessment/skill test has an associated marking guide and recommended solution available, to help you assess their work. 71 | 5. There are patterns that make it easier to find these resources, for example: 72 | 73 | - The above "test your skills" marking guide and resources are available at . 74 | - The above assessment marking guide and resources are available at . 75 | 76 | It will seem tricky to navigate around all this to begin with, but you'll find it easier in time, as you become more familiar with the exercises. 77 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/writing-style-guide/code-style-guide/html/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Guidelines for styling HTML code examples 3 | slug: 4 | tags: 5 | - Code 6 | - Guide 7 | - Guidelines 8 | - HTML 9 | - MDN Meta 10 | --- 11 | {{MDNSidebar}} 12 | 13 | The following guidelines cover how to write HTML example code for MDN Web Docs. 14 | 15 | ## General guidelines for HTML code examples 16 | 17 | > **Note:** The guidelines in this section apply only when you need to show a complete HTML document. A snippet is usually enough to demonstrate a feature. When using the [EmbedLiveSample macro](/en-US/docs/MDN/Structures/Code_examples#traditional_live_samples), just include the HTML snippet; it will automatically be inserted into a full HTML document when displayed. 18 | 19 | ### Doctype 20 | 21 | You should use the HTML5 doctype. It is short, easy to remember, and backwards compatible. 22 | 23 | ```html example-good 24 | 25 | ``` 26 | 27 | ### Document language 28 | 29 | Set the document language using the {{htmlattrxref('lang')}} attribute on your {{htmlelement("html")}} element: 30 | 31 | ```html example-good 32 | 33 | ``` 34 | 35 | This is good for accessibility and search engines, helps with localizing content, and reminds people to use best practices. 36 | 37 | ### Document characterset 38 | 39 | You should also define your document's characterset like so: 40 | 41 | ```html example-good 42 | 43 | ``` 44 | 45 | Use UTF-8 unless you have a very good reason not to; it will cover all character needs pretty much regardless of what language you are using in your document. In addition, you should always specify the characterset as early as possible within your HTML's {{HTMLElement("head")}} block (within the first kilobyte), as it protects against a rather [nasty Internet Explorer security vulnerability](https://docs.microsoft.com/en-US/troubleshoot/developer/browsers/development-website/wrong-character-set-for-html-page). 46 | 47 | ### Viewport meta tag 48 | 49 | Finally, you should always add the viewport meta tag into your HTML {{HTMLElement("head")}} to give the code example a better chance of working on mobile devices. You should include at least the following in your document, which can be modified later on as the need arises: 50 | 51 | ```html example-good 52 | 53 | ``` 54 | 55 | See [Using the viewport meta tag to control layout on mobile browsers](/en-US/docs/Web/HTML/Viewport_meta_tag) for further details. 56 | 57 | ## Guidelines for HTML coding style 58 | 59 | ### Attributes 60 | 61 | You should put all attribute values in double quotes. It is tempting to omit quotes since HTML5 allows this, but markup is neater and easier to read if you do include them. For example, this is better: 62 | 63 | ```html example-good 64 | A circular globe icon 65 | ``` 66 | 67 | …than this: 68 | 69 | ```html example-bad 70 | A 71 | ``` 72 | 73 | Omitting quotes can also cause problems. In the above example, the `alt` attribute will be interpreted as multiple attributes because there are no quotes to specify that "A circular globe icon" is a single attribute value. 74 | 75 | ### Boolean attributes 76 | 77 | Don't write out boolean attributes in full; you can just write the attribute name to set it. For example, you can write: 78 | 79 | ```html example-good 80 | required 81 | ``` 82 | 83 | This is perfectly understandable and works fine; the longer version with the value is supported but not necessary: 84 | 85 | ```html example-bad 86 | required="required" 87 | ``` 88 | 89 | ### Case 90 | 91 | Use lowercase for all element names and attribute names/values because it looks neater and means you can write markup faster. For example: 92 | 93 | ```html example-good 94 |

This looks nice and neat

95 | ``` 96 | 97 | ```html example-bad 98 |

Why is my markup shouting?

99 | ``` 100 | 101 | ### Class and ID names 102 | 103 | Use semantic class/ID names, and separate multiple words with hyphens. Don't use camelCase. For example: 104 | 105 | 106 | ```html example-good 107 |

Blah blah blah

108 | ``` 109 | 110 | ```html example-bad 111 |

Blah blah blah

112 | ``` 113 | 114 | ### Double quotes 115 | 116 | Use double quotes for HTML, not single quotes, like so: 117 | 118 | ```html example-good 119 |

Yes

120 | ``` 121 | 122 | ```html example-bad 123 |

Nope

124 | ``` 125 | 126 | ### Entity references 127 | 128 | Don't use entity references unnecessarily — use the literal character wherever possible (you'll still need to escape characters like angle brackets and quote marks). 129 | 130 | As an example, you could just write: 131 | 132 | ```html example-good 133 |

© 2018 Me

134 | ``` 135 | 136 | Instead of: 137 | 138 | ```html example-bad 139 |

© 2018 Me

140 | ``` 141 | 142 | This is fine as long as you declare a UTF-8 character set. 143 | 144 | ### HTML elements 145 | 146 | There are some rules for writing about HTML elements on MDN Web Docs. Adhering to these rules produces consistent descriptions of elements and their components and also ensures correct linking to detailed documentation. 147 | 148 | - **Element names**: Use the [`HTMLElement`](https://github.com/mdn/yari/blob/main/kumascript/macros/HTMLElement.ejs) macro, which creates a link to the MDN Web Docs page for that element. 149 | > For example, writing `\{{HTMLElement("title")}}` produces "{{HTMLElement("title")}}". 150 | If you don't want to create a link, **enclose the name in angle brackets** and use the "Inline Code" style (e.g., ``). 151 | - **Attribute names**: Use "Inline Code" style to put attribute names in `code font`. 152 | Additionally, put them in **`bold face`** when the attribute is mentioned in association with an explanation of what it does or when it is used for the first time on the page. 153 | - **Attribute definitions**: Use the [`htmlattrdef`](https://github.com/mdn/yari/blob/main/kumascript/macros/htmlattrdef.ejs) macro (e.g., `\{{htmlattrdef("type")}})` for the definition term. This allows the term definition to be linked from other pages easily by using the [`htmlattrxref`](https://github.com/mdn/yari/blob/main/kumascript/macros/htmlattrxref.ejs) macro (e.g., `\{{htmlattrxref("type","element")}}`). 154 | - **Attribute values**: Use the "Inline Code" style to apply `<code>` to attribute values, and don't use quotation marks around string values, unless needed by the syntax of a code sample. For example, "When the `type` attribute of an `<input>` element is set to `email` or `tel` ...". 155 | 156 | ### Trailing slashes <!--Is this still a valid section to keep?--> 157 | 158 | Don't include XHTML-style trailing slashes for empty elements because they're unnecessary and slow things down. They can also break old browsers if you're not careful (although from what we can recall, this hasn't been a problem since Netscape 4). For example: 159 | 160 | ```html example-good 161 | <input type="text"> 162 | <hr> 163 | ``` 164 | 165 | ```html example-bad 166 | <input type="text" /> 167 | <hr /> 168 | ``` 169 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/creating-moving-archiving-pages/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Creating, moving, and deleting pages 3 | slug: MDN/Writing_guidelines/Creating_moving_deleting 4 | page-type: mdn-writing-guide 5 | tags: 6 | - meta 7 | - writing-guide 8 | --- 9 | {{MDNSidebar}} 10 | 11 | This article describes how to create, move, or delete a page. In all these instances, it's a good idea to check our [What we write](/en_US/docs/MDN/Writing_guidelines/What_we_write) guidelines to confirm if any of these actions should be taken and discuss it with the MDN Web Docs team <!--add contact link here--> before going ahead. 12 | 13 | ## Creating pages 14 | 15 | All pages are on MDN Web Docs are authored in markdown format. The content is written in the file named `index.md`, which is stored in its own unique directory. The directory name represents the name of the page. For example, if `align-content` is a new CSS property for which you want to create a new reference page, you'd create a folder in `en-us/web/css` named `align-content` and create a file called `index.md` inside it. 16 | 17 | > **Note:** The name of the directory differs slightly from the slug of the page. Most notably, the slug follows sentence casing. 18 | 19 | There are lots of different [page types with certain structures](/en_US/docs/MDN/Writing_guidelines/How_to_write/Page_types) and supporting page templates for them, which you can copy to get you started. <!--link to be done--> 20 | 21 | A document's `index.md` file must start with front matter that defines the `title`, `slug`, `page-type`, and `tags`. All of this front matter information can be found in the aforementioned page templates. Alternatively, you might find it helpful to refer to the front matter within a similar document's `index.md`. 22 | 23 | The general step-by-step process for creating a page would be: 24 | 25 | 1. Start a fresh, up-to-date branch to work in. 26 | 27 | ```sh 28 | cd ~/repos/mdn/content 29 | git checkout main 30 | git pull mdn main 31 | # Run "yarn" again to ensure you've 32 | # installed the latest Yari dependency. 33 | yarn 34 | git checkout -b my-add 35 | ``` 36 | 37 | 2. Create one or more new document folders, each with their own `index.md` files. 38 | 39 | 3. Add and commit your new files, as well as push your new branch to your fork. 40 | 41 | ```sh 42 | git add files/en-us/folder/you/created 43 | git commit 44 | git push -u origin my-add 45 | ``` 46 | 47 | 4. Create your pull request. 48 | 49 | ## Moving pages 50 | 51 | Moving one or more documents or an entire tree of documents is easy 52 | because we've created a special command that takes care of the details for you: 53 | 54 | ```sh 55 | yarn content move <from-slug> <to-slug> [locale] 56 | ``` 57 | 58 | You just have to specify the slug of the existing document that you'd like 59 | to move (e.g., `Learn/Accessibility`), as well as the slug of its new 60 | location (e.g., `Learn/A11y`), optionally followed by the locale of the 61 | existing document (defaults to `en-US`). 62 | If the existing document that you'd like to move has child documents (i.e. 63 | it represents a document tree), the `yarn content move` command will move 64 | the entire tree. For example, let's say you want to move the entire 65 | `/en-US/Learn/Accessibility` tree to `/en-US/Learn/A11y`, you'd perform the following steps: 66 | 67 | 1. You'll start a fresh branch to work in. 68 | 69 | ```sh 70 | cd ~/repos/mdn/content 71 | git checkout main 72 | git pull mdn main 73 | # Run "yarn" again just to ensure you've 74 | # installed the latest Yari dependency. 75 | yarn 76 | git checkout -b my-move 77 | ``` 78 | 79 | 2. Perform the move (which will delete and modify existing files, as well 80 | as create new files). 81 | 82 | ```sh 83 | yarn content move Learn/Accessibility Learn/A11y 84 | ``` 85 | 86 | 3. Add and commit all of the deleted, created, and modified files, as well as 87 | push your branch to your fork. 88 | 89 | ```sh 90 | git commit -a 91 | git push -u origin my-move 92 | ``` 93 | 94 | 4. Create your pull request. 95 | 96 | > **Note:** `yarn content move` automatically adds the necessary redirect 97 | information to the `_redirects.txt` file so that the old location will redirect 98 | to the new one. Don't edit the `_redirects.txt` file manually! 99 | Mistakes can easily creep in if you do. If you need to add a redirect without 100 | moving a file, talk to the MDN Web Docs team <!--add link to contact--> about it. 101 | 102 | ## Deleting pages 103 | 104 | Documents should only be removed from MDN Web Docs under special circumstances. If you are thinking about deleting pages, please discuss it with the MDN Web Docs team <!--add link to contact--> first. 105 | 106 | Deleting one or more documents or an entire tree of documents is easy, just like moving pages, because we've created a special command that takes care of the 107 | details for you: 108 | 109 | ```sh 110 | yarn content delete <document-slug> [locale] 111 | ``` 112 | 113 | You just have to specify the slug of the existing document that you'd like 114 | to delete (e.g., `Learn/Accessibility`), optionally followed by the locale 115 | of the existing document (defaults to `en-US`). If the existing document 116 | that you'd like to delete has child documents (i.e. it represents a 117 | document tree), you must also specify the `-r, --recursive` option, otherwise 118 | the command will fail. 119 | 120 | > **Important:** You need to use the `yarn content delete` command to delete pages from MDN Web Docs. Don't 121 | just delete their directories from the repo. The `yarn content delete` command also handles other necessary changes such as updating the `_wikihistory.json` file. 122 | 123 | 124 | For example, if you want to delete the 125 | entire `/en-US/Learn/Accessibility` tree, you'd perform the following steps: 126 | 127 | 1. You'll start a fresh branch to work in. 128 | 129 | ```sh 130 | cd ~/repos/mdn/content 131 | git checkout main 132 | git pull mdn main 133 | # Run "yarn" again just to ensure you've 134 | # installed the latest Yari dependency. 135 | yarn 136 | git checkout -b my-delete 137 | ``` 138 | 139 | 2. Perform the delete. 140 | 141 | ```sh 142 | yarn content delete Learn/Accessibility --recursive 143 | ``` 144 | 145 | 3. Add a redirect. The target page can be an external URL or another page on MDN Web Docs. 146 | 147 | ```sh 148 | yarn content add-redirect /en-US/path/of/deleted/page /en-US/path/of/target/page 149 | ``` 150 | 151 | 4. Add and commit all of the deleted files, as well as 152 | push your branch to your fork. 153 | 154 | ```sh 155 | git commit -a 156 | git push -u origin my-delete 157 | ``` 158 | 159 | 5. Create your pull request. 160 | 161 | ```sh 162 | yarn content delete "Mozilla/Add-ons/WebExtensions/Debugging_(before_Firefox_50)" 163 | ``` 164 | 165 | > **Note:** If the slug of the page you wish to delete contains special characters, include it in quotes, like so: 166 | 167 | ```sh 168 | yarn content delete "Mozilla/Add-ons/WebExtensions/Debugging_(before_Firefox_50)" 169 | ``` 170 | 171 | Removing content from MDN Web Docs will inevitably result in updating existing content as well, as a lot of articles link to others, the removed content will be referenced elsewhere. 172 | 173 | Adding the redirect will mitigate the impact of removing content; however, it's best practice to edit content to reflect the change and include the edits alongside the removal pull request. 174 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/what-we-write/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: What we write 3 | slug: MDN/Writing_guidelines/What_we_write 4 | page-type: mdn-writing-guide 5 | tags: 6 | - meta 7 | - writing-guide 8 | --- 9 | {{MDNSidebar}} 10 | 11 | MDN Web Docs contains _browser-neutral_ documentation that enables web developers to write _browser-agnostic_ code. In this article, you'll find information about whether or not a given topic and/or type of content should be included on MDN Web Docs. 12 | 13 | ## Suggesting content 14 | 15 | If you'd like to suggest content for MDN Web Docs, please make sure you read this page before submitting to ensure what you are suggesting is appropriate. 16 | 17 | For new reference pages or guides please open a discussion on [our community repository](https://github.com/mdn/mdn-community/discussions/categories/content-suggestions) outlining what content you are suggesting and why (please be as explicit as possible). 18 | 19 | For suggesting larger projects which involve new sections of content, please refer to the [Inclusion criteria page](/en_US/docs/MDN/Writing_guidelines/What_we_write/Inclusion_criteria) which also outlines the application process. 20 | 21 | ## Topics that belong on MDN Web Docs 22 | 23 | In general, if it's an open web technology, we document it on MDN Web Docs. This includes any feature that can be used by web developers to create websites and applications, now and in the near future. 24 | 25 | If a feature is implemented by multiple browsers and either accepted as standard or is progressing towards standardization, then yes, we definitely document it here. If a feature is still very experimental and not implemented in multiple browsers and/or liable to change, then it is still suitable for inclusion, but may not be seen as a priority for the writer's team to work on. 26 | 27 | In other words, web technologies to be documented on MDN Web Docs should fulfil the following criteria: 28 | 29 | - Be on a standards track. 30 | - Be specified in a specification published by a reliable standards body. 31 | - Be implemented by at least one rendering engine. 32 | - Be released in a stable browser version. 33 | 34 | Our primary focus is to write about the following front-end web technologies: 35 | 36 | - [HTML](/en-US/docs/Web/HTML) 37 | - [CSS](/en-US/docs/Web/CSS) 38 | - [JavaScript](/en-US/docs/Web/JavaScript) 39 | - [Web APIs](/en-US/docs/Web/API) 40 | - [HTTP](/en-US/docs/Web/HTTP) 41 | 42 | We also document some broader topics, such as [SVG](/en-US/docs/Web/SVG), [XML](/en-US/docs/Web/XML), [WebAssembly](/en-US/docs/WebAssembly), and [Accessibility](/en-US/docs/Learn/Accessibility). In addition, we provide extensive [learning guides](/en-US/docs/Learn) for these technologies and also a [glossary](/en-US/docs/Glossary). 43 | 44 | > **Note:** Backend technologies usually have their own documentation elsewhere that MDN Web Docs does not attempt to supersede, although we [do have some exceptions](/en-US/docs/Learn/Server-side). 45 | 46 | All content on MDN Web Docs must be relevant to the technology section in which it appears. Contributors are expected to follow these [MDN writing guidelines](/en-US/docs/MDN/Writing_guidelines) for writing style, code samples, and other topics. 47 | 48 | For more details on acceptance criteria for whether or not a technology can be documented on MDN Web Docs, see the [Criteria for inclusion]<!--- add link---> 49 | 50 | ### When we document a new technology 51 | 52 | On MDN web Docs, we are constantly looking to document new web standards technologies as appropriate. 53 | We try to strike a balance between publishing the documentation early enough so that developers can learn about new features as soon as they need to and publishing it late enough so that the technology is mature and stable so the documentation won't need constant updates or rapid removal. 54 | 55 | In general, our definition of the earliest we'll consider documenting a new technology is: 56 | 57 | _"When the feature is on a standards track and is implemented somewhere."_ 58 | 59 | We consider documenting a new technology if: 60 | 61 | - It is specified in a specification document published under a reliable standards organization (such as W3C, WHATWG, Khronos, IETF, etc.) and has reached a reasonable level of stability (e.g., a W3C working draft or candidate recommendation or when the specification is looking fairly stable judging by the flow of issues filed against it). 62 | - It is implemented consistently in at least one browser, with other browser developers showing signs of interest (such as an active ticket or an "intent to implement" process is in effect). 63 | 64 | We do not document a new technology if it: 65 | 66 | - Doesn't have a specification or the specification is a rough note that looks liable to change. 67 | - One or zero browsers have currently implemented it and non-supporting browsers are not showing signs of interest in implementing it. You can gauge this by asking engineers who work on those browsers and by looking at browser bug trackers and mailing lists, etc. 68 | - Not a web-exposed technology and/or is completely proprietary. 69 | - Already showing signs of being deprecated or superseded by a similar feature. 70 | 71 | ## Topics that don't belong on MDN Web Docs 72 | 73 | In general, anything that isn't an open web standard does not belong on MDN Web Docs. Spam (commercial advertisement) and other irrelevant content will never be accepted into the site. Contributors who keep trying to submit spam may be banned from MDN at the discretion of Mozilla MDN staff. 74 | 75 | Examples of inappropriate topics for MDN Web Docs include: 76 | 77 | - Technology that is not exposed to the web and is specific to a browser. 78 | - Technology that is not related to the web. 79 | - Documentation for end-users. For Mozilla products, for example, such documentation belongs on the [Mozilla support site](https://support.mozilla.org). 80 | - Self-linking or self-promoting external links. Check out these guidelines before adding an external link. 81 | 82 | ### When we remove documentation 83 | 84 | Pages are deleted from MDN Web Docs if they don't contain information that is useful in any way anymore, are out-of-date enough, and/or might be incorrect to the point where keeping them around might be misleading. 85 | 86 | Pages might be deleted when: 87 | 88 | - Articles containing information about features that weren't implemented across all browsers and have later been withdrawn (usually experimental features such as prefixed functionality). 89 | - Reference pages for features that were removed from the specification before they were implemented in any browser. 90 | - Articles covering techniques that were later shown to be bad practices and superseded by better techniques. 91 | - Articles containing information that were later replaced by other, better quality articles. 92 | - Articles containing content that is inappropriate for MDN Web Docs. 93 | - Sections of MDN Web Docs which are not focused on open web technologies and are a maintenance burden. 94 | 95 | For more information on _how_ to delete documents, please see the [Creating, moving and deleting pages guide]() 96 | 97 | 98 | ## Types of documents on MDN Web Docs 99 | 100 | Generally our documentation falls into the following categories: 101 | 102 | - Reference 103 | - Guide 104 | - Glossary 105 | - Learn/Tutorials 106 | 107 | In general, MDN Web Docs is for _product_ documentation, not for _project_ or _process_ documentation. So, if the document is about "how to use a thing" or "how a thing works" (where, the "thing" is in one of the topic categories mentioned above), then it can go on MDN Web Docs. 108 | 109 | If a document is about "who's working on developing a thing" or "plans for developing a thing", then it shouldn't go on MDN Web Docs. 110 | 111 | Here are some examples of types of documents that should _not_ be placed on MDN Web Docs: 112 | 113 | - Planning documents 114 | - Design documents 115 | - Project proposals 116 | - Specifications or standards 117 | - Promotional material, advertising, or personal information 118 | 119 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/page-structure/page-types/api/sidebars/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: API reference sidebars 3 | slug: MDN/Contribute/Howto/Write_an_API_reference/Sidebars 4 | tags: 5 | - API 6 | - Documentation 7 | - Guide 8 | - MDN 9 | - MDN Meta 10 | - Reference 11 | - groupdata 12 | - metadata 13 | - onboarding 14 | - sidebars 15 | --- 16 | {{MDNSidebar}} 17 | 18 | You are able to include a custom sidebar on API reference pages it so that it displays links to related Interfaces, tutorials, and other resources relevant just to that API. 19 | This article explains how. 20 | 21 | ## Creating a sidebar 22 | 23 | You need to take the following three steps to create your API sidebar: 24 | 25 | 1. Create your API reference pages. 26 | 2. Add an entry for your particular API into the [`GroupData.json`](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) file. 27 | 3. Use the [`APIRef`](https://github.com/mdn/yari/blob/main/kumascript/macros/APIRef.ejs) macro to insert the sidebar into each page you want to display it on. 28 | 29 | Let's run through each of these steps in turn. 30 | The example we'll refer to in this article is the [Fetch API](/en-US/docs/Web/API/Fetch_API). 31 | 32 | ### Adding an entry to GroupData.json 33 | 34 | The `GroupData.json` file holds all the data relating to what links should appear in API reference sidebars. 35 | When invoked, the `APIRef` macro takes an API name given to it as a parameter, looks up that name in `GroupData.json`, builds an appropriate sidebar, and inserts it into the page. 36 | 37 | To add an entry to `GroupData.json`, you need to: 38 | 39 | 1. Make sure you have a [GitHub](https://github.com/) account. 40 | 2. Fork the MDN content repo, create a new branch to contain your changes, and clone the repo locally. 41 | 3. Checkout your new branch before starting work, and make sure you push changes to it after finishing. 42 | 4. Create a pull request so that the MDN team can review your work, and ask for changes if necessary. 43 | 44 | The `GroupData.json` file can be found inside the `files/jsondata/` directory. 45 | Looking at it, you'll see a giant JSON structure, with each API having its own member. 46 | The name is the API name, and the value is an object containing several sub-members defining the sidebar links to be created. 47 | 48 | For example, look at the [Fetch API](/en-US/docs/Web/API/Fetch_API) page on MDN. 49 | The corresponding entry in `GroupData.json` looks like this: 50 | 51 | ```json 52 | "Fetch API": { 53 | "overview": [ "Fetch API"], 54 | "interfaces": [ "Headers", 55 | "Request", 56 | "Response", 57 | "FetchController", 58 | "FetchObserver", 59 | "FetchSignal", 60 | "ObserverCallback" ], 61 | "methods": [ "fetch()" ], 62 | "properties": [], 63 | "events": [] 64 | }, 65 | ``` 66 | 67 | As you can see, we've used "Fetch API" for the name, and inside the object value we include a number of sub-members. 68 | 69 | #### Sub-members to include inside a GroupData entry 70 | 71 | This section lists all the sub-members you could include in a `GroupData` entry. 72 | 73 | Note that most of the values included inside the listed sub-members equate to both the link text, and slugs appended to the end of the main API index page — `https://developer.mozilla.org/<language-code>/docs/Web/API` — to create the final URL for the displayed link. 74 | So for example, "Response" will result in a link being created like so: 75 | 76 | ```html 77 | <li><a href="/en-US/docs/Web/API">Response</a></li> 78 | ``` 79 | 80 | There are a few exceptions. 81 | For example the "guides" sub-member contains one or more sets of link information (title and slug) that defines links to associated guides/tutorials. 82 | In this case the slugs are appended to the end of the MDN docs root — https\://developer.mozilla.org/_\<language-code>_/docs — allowing an article anywhere on MDN to be included. 83 | 84 | Here are the available members. 85 | These are all technically optional, but it is strongly encouraged that instead of omitting them, you include empty arrays. 86 | 87 | 1. `"overview"` — the value is an array, inside of which you include the slug of the API overview page, if there is one. 88 | "Fetch API" results in a link being made to [https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API](/en-US/docs/Web/API/Fetch_API). 89 | 2. `"interfaces"` — the value is an array in which you should list all of the interfaces that form part of that API. 90 | "Response" results in a link being made to [https://developer.mozilla.org/en-US/docs/Web/API/Response](/en-US/docs/Web/API/Response). 91 | 3. `"methods"` — the value is an array that should contain any methods the spec adds to interfaces associated with other APIs, such as instantiation methods created on {{domxref("Navigator")}} or {{domxref("Window")}}. 92 | If there are a huge number of methods, you might want to consider only listing the most popular ones, or putting them first in the list. 93 | "fetch()" results in a link being made to [https://developer.mozilla.org/en-US/docs/Web/API/fetch](/en-US/docs/Web/API/fetch). 94 | Do _not_ list methods that are members of interfaces that are members of interfaces that are owned by the same API. 95 | 4. `"properties"` — the value is an array that should contain all of the properties associated with the API. 96 | This can include properties that are members of interfaces defined in the API spec, and properties the API defines on other interfaces. 97 | If there are a huge number of properties, you might want to consider only listing the most popular ones, or putting them first in the list. 98 | "Headers.append" results in a link being made to [https://developer.mozilla.org/en-US/docs/Web/API/Headers/append](/en-US/docs/Web/API/Headers/append). 99 | 5. `"events"` — the value is an array that should contain all of the events associated with the API, defined in the API spec, or elsewhere. 100 | If there are a huge number of events, you might want to consider only listing the most popular ones, or putting them first in the list. 101 | "animationstart" results in a link being made to [https://developer.mozilla.org/en-US/docs/Web/Events/animationstart](/en-US/docs/Web/API/HTMLElement/animationstart_event). 102 | 6. `"guides"` — the value is an array containing one or more objects that define links to guides explain how to use the API. 103 | Each object contains two sub-members — "url", which contains the partial URL pointing to the guide article, and "title", which defines the link test for the link. 104 | As an example, the following object: 105 | 106 | ```json 107 | { "url": "/docs/Web/API/Detecting_device_orientation", 108 | "title": "Detecting device orientation" } 109 | ``` 110 | 111 | Creates a link with the title "Detecting device orientation", which points to [https://developer.mozilla.org/en-US/docs/Web/Events/Detecting_device_orientation](/en-US/docs/Web/Events/Detecting_device_orientation). 112 | 113 | 7. `"dictionaries"` — an array of strings listing all of the dictionaries which are part of the API. 114 | Generally, only dictionaries used by more than one property or method should be listed here, unless they are of special significance or are likely to require being referenced from multiple pages. 115 | "CryptoKeyPair" results in a link to [https://developer.mozilla.org/en-US/docs/Web/API/CryptoKeyPair](/en-US/docs/Web/API/CryptoKeyPair). 116 | > **Note:** MDN is moving away from separately documenting dictionaries. 117 | > Where possible, these are now described as objects in the places where they are used. 118 | 8. `"types"` — an array of typedefs and enumerated types defined by the API. 119 | You may choose to only list those that are of special importance or are referenced from multiple pages, in order to keep the list short. 120 | "RTCSctpTransportState" creates a link to [https://developer.mozilla.org/en-US/docs/Web/API/RTCSctpTransportState](/en-US/docs/Web/API/RTCSctpTransport/state). 121 | 9. `"callbacks"` — the value is an array containing a list of all the defined callback types for the API. 122 | You may find it unnecessary to use this group at all, even on APIs that include callback types, as often they are not useful to document separately. 123 | 124 | ## Tags used by sidebars 125 | 126 | Some sub-members are automatically discovered from child pages, based on page tags. 127 | Pages under the top-level API are crawled each time the sidebar is rendered, and entries are automatically created for methods ("Method" tag), properties ("Property" tag), and constructors ("Constructor" tag). 128 | 129 | Sub-members are automatically decorated with warning icons based on tags as well. 130 | Decorations are added for experimental ("Experimental" tag), non-standard ("Non Standard" or "Non-standard" tag), or deprecated ("Deprecated" tag) sub-members. 131 | 132 | Further information about tag-based processing is available [in the APIRef source](https://github.com/mdn/yari/blob/main/kumascript/macros/APIRef.ejs). 133 | 134 | ## Inserting the sidebar 135 | 136 | Once you've added an entry for your API into `GroupData.json`, submitted it as a pull request and had the change accepted into the main repo, you can include it in your API reference pages using the [`APIRef`](https://github.com/mdn/yari/blob/main/kumascript/macros/APIRef.ejs) macro, which takes the name you used for your API in GroupData as a parameter. 137 | As an example, the [WebVR API](/en-US/docs/Web/API/WebVR_API)'s sidebar is included in its pages with the following: 138 | 139 | ```js 140 | \{{APIRef("WebVR API")}} 141 | ``` 142 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/writing-style-guide/code-style-guide/css/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Guidelines for styling CSS code examples 3 | slug: 4 | tags: 5 | - CSS 6 | - Code 7 | - Guide 8 | - Guidelines 9 | - MDN Meta 10 | --- 11 | {{MDNSidebar}} 12 | 13 | The following guidelines cover how to write CSS example code for MDN Web Docs. 14 | 15 | ## General guidelines for CSS code examples 16 | 17 | ### Plan your CSS 18 | 19 | Before diving in and writing huge chunks of CSS, plan your styles carefully. What general styles are going to be needed, what different layouts do you need to create, what specific overrides need to be created, and are they reusable? Above all, you need to try to **avoid too much overriding**. If you keep finding yourself writing styles and then cancelling them again a few rules down, you probably need to rethink your strategy. 20 | 21 | ### Use flexible/relative units 22 | 23 | For maximum flexibility over the widest possible range of devices, it is a good idea to size containers, padding, etc. using relative units like ems and rems or percentages and viewport units if you want them to vary depending on viewport width. You can read some more about this in our [Responsive design building blocks](/en-US/docs/Web/Progressive_web_apps/Responsive/responsive_design_building_blocks#fluid_grids) article. 24 | 25 | ### Don't use preprocessors 26 | 27 | Don't use preprocessor syntax, such as [Sass](https://sass-lang.com/), [Less](https://lesscss.org/), or [Stylus,](https://stylus-lang.com/), in the example code. On MDN Web Docs, we document the vanilla CSS language. Using preprocessors will only raise the bar to understanding the examples, potentially confusing readers. 28 | 29 | ### Don't use specific CSS methodologies 30 | 31 | In the same spirit as the previous guideline, don't write example codes on MDN Web Docs using a specific CSS methodology such as [BEM](http://getbem.com/naming/) or [SMACSS](http://smacss.com/). Even though they are valid CSS syntax, the naming conventions can be confusing to people not familiar with those methodologies. 32 | 33 | ### Don't use resets <!--is this valid in current times--> 34 | 35 | For maximum control over CSS across platforms, a lot of people used to use CSS resets to remove every style, before then building things back up themselves. This certainly has its merits, but especially in the modern world, CSS resets can be an overkill, resulting in a lot of extra time spent reimplementing things that weren't completely broken in the first place, like default margins, list styles, etc. 36 | 37 | If you really feel like you need to use a reset, consider using [normalize.css by Nicolas Gallagher](https://necolas.github.io/normalize.css/), which aims to just make things more consistent across browsers, get rid of some default annoyances that we always remove (the margins on `<body>`, for example) and fix a few bugs. 38 | 39 | ## !important 40 | 41 | `!important` is the last resort that is generally used only when you need to override something and there is no other way to do it. Using `!important` is a bad practice and you should avoid it wherever possible. 42 | 43 | ```css example-bad 44 | .bad-code { 45 | font-size: 4rem !important; 46 | } 47 | ``` 48 | 49 | ## CSS comments 50 | 51 | Use CSS-style comments to comment code that isn't self-documenting. Also note that you should leave a space between the asterisks and the comment. 52 | 53 | ```css example-good 54 | /* This is a CSS-style comment */ 55 | ``` 56 | 57 | Put your comments on separate lines preceding the code they are referring to, like so: 58 | 59 | ```css example-good 60 | h3 { 61 | /* Creates a red drop shadow, offset 1px right and down, w/2px blur radius */ 62 | text-shadow: 1px 1px 2px red; 63 | /* Sets the font-size to double the default document font size */ 64 | font-size: 2rem; 65 | } 66 | ``` 67 | 68 | ## Double quotes around values 69 | 70 | Where quotes can or should be included, use them, and use double quotes. For example: 71 | 72 | ```css example-good 73 | [data-vegetable="liquid"] { 74 | background-color: goldenrod; 75 | background-image: url("../../media/examples/lizard.png"); 76 | } 77 | ``` 78 | 79 | ## Longhand vs. shorthand rules 80 | 81 | Usually when teaching the specifics of CSS syntax, it is clearer and more obvious to use longhand properties, rather than terse shorthand (unless of course you're explaining shorthand through the example). Remember that the point of examples on MDN Web Docs is to teach people, not to be clever or efficient. We explain here why recommend writing longhand rules. 82 | 83 | - It is often harder to understand what the shorthand is doing. In the example below, it takes a while to pick apart exactly what the {{cssxref("font")}} syntax is doing. 84 | 85 | ```css 86 | font: small-caps bold 2rem/1.5 sans-serif; 87 | ``` 88 | 89 | Whereas the following style is clearer: 90 | 91 | ```css 92 | font-variant: small-caps; 93 | font-weight: bold; 94 | font-size: 2rem; 95 | line-height: 1.5; 96 | font-family: sans-serif; 97 | ``` 98 | 99 | - CSS shorthand comes with potential added pitfalls — default values are set for parts of the syntax that you don't explicitly set, which can produce unexpected resets of values you've set earlier in the cascade or other expected effects. The {{cssxref("grid")}} property, for example, sets all of the following default values for items that are not specified: 100 | 101 | - {{cssxref("grid-template-rows")}}: `none` 102 | - {{cssxref("grid-template-columns")}}: `none` 103 | - {{cssxref("grid-template-areas")}}: `none` 104 | - {{cssxref("grid-auto-rows")}}: `auto` 105 | - {{cssxref("grid-auto-columns")}}: `auto` 106 | - {{cssxref("grid-auto-flow")}}: `row` 107 | - {{cssxref("column-gap")}}: `0` 108 | - {{cssxref("row-gap")}}: `0` 109 | - {{cssxref("column-gap")}}: `normal` 110 | - {{cssxref("row-gap")}}: `normal` 111 | 112 | - Some shorthands only work as expected if you include the different value components in a certain order. This is the case in CSS animations. In the example below, the expected order is written as a comment: 113 | 114 | ```css 115 | /* duration | timing-function | delay | iteration-count 116 | direction | fill-mode | play-state | name */ 117 | animation: 3s ease-in 1s 2 reverse both paused slidein; 118 | ``` 119 | 120 | In this example, the first value that can be parsed as a [`<time>`](/en-US/docs/Web/CSS/time) is assigned to the [`animation-duration`](/en-US/docs/Web/CSS/animation-duration) property, and the second value that can be parsed as time is assigned to [`animation-delay`](/en-US/docs/Web/CSS/animation-delay). (For more information, see [animation syntax](/en-US/docs/Web/CSS/animation#syntax) details.) 121 | 122 | ## Mobile-first media queries 123 | 124 | In a stylesheet that contains [media query](/en-US/docs/Web/CSS/Media_Queries/Using_media_queries) styles for different target viewport sizes, first include the narrow screen/mobile styling before any other media queries are encountered. Add styling for wider viewport sizes via successive media queries. Following this rule has many advantages that are explained in the [Mobile First](/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first) article. 125 | 126 | ```css example-good 127 | /* Default CSS layout for narrow screens */ 128 | 129 | @media (min-width: 480px) { 130 | /* CSS for medium width screens */ 131 | } 132 | 133 | @media (min-width: 800px) { 134 | /* CSS for wide screens */ 135 | } 136 | 137 | @media (min-width: 1100px) { 138 | /* CSS for really wide screens */ 139 | } 140 | ``` 141 | 142 | ## Selectors 143 | 144 | - Don't use ID selectors because they are: 145 | - less flexible; you can't add more if you discover you need more than one. 146 | - harder to override because they have higher specificity than classes. 147 | 148 | ```css example-good 149 | .editorial-summary { 150 | ... 151 | } 152 | ``` 153 | 154 | ```css example-bad 155 | #editorial-summary { 156 | ... 157 | } 158 | ``` 159 | 160 | - When a rule has multiple selectors, put each selector on a new line. This makes the selector list easier to read and can help to make code lines shorter. 161 | 162 | Do this: 163 | 164 | ```css example-good 165 | h1, 166 | h2, 167 | h3 { 168 | font-family: sans-serif; 169 | text-align: center; 170 | } 171 | ``` 172 | 173 | Not this: <!--I thought this is the preferred style--> 174 | 175 | ```css example-bad 176 | h1, h2, h3 { 177 | font-family: sans-serif; 178 | text-align: center; 179 | } 180 | ``` 181 | 182 | ## Space after function parameters 183 | 184 | Function parameters should have spaces after their separating commas, but not before: 185 | 186 | ```css example-good 187 | color: rgb(255, 0, 0); 188 | background-image: linear-gradient(to bottom, red, black); 189 | ``` 190 | 191 | ## Syntax style 192 | 193 | There are a variety of CSS writing styles you can use, but we prefer the expanded style, with the selector/opening brace, close brace, and each declaration on a separate line. This maximizes readability, and again, promotes consistency on MDN Web Docs. 194 | 195 | In addition, keep these specifics in mind: 196 | 197 | - Include a space between the selector(s) and the opening curly brace. 198 | - Always include a semi-colon at the end of the last declaration, even though it isn't strictly necessary. 199 | - Put the closing curly brace on a new line. 200 | - In each declaration, put a space after the separating colon, but not before. 201 | - Use two spaces for code indentation. 202 | 203 | ```css example-good 204 | p { 205 | color: white; 206 | background-color: black; 207 | padding: 1rem; 208 | } 209 | ``` 210 | 211 | ```css example-bad 212 | p { color: white; background-color: black; padding: 1rem; } 213 | ``` 214 | 215 | ## Value to turn off properties 216 | 217 | When turning off borders (and any other properties that can take `0` or `none` as values), use `0` rather than `none`: 218 | 219 | ```css example-good 220 | border: 0; 221 | ``` 222 | 223 | ## See also 224 | 225 | [CSS reference index](/en-US/docs/Web/CSS/Reference#index) - browse through our CSS property reference pages to check out some good, concise, meaningful CSS snippets. Our interactive examples in the "Try it" section are generally written to follow the guidelines described on this page. 226 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/page-structure/code-examples/index.md: -------------------------------------------------------------------------------- 1 | <!-- Captured --> 2 | 3 | This document series outlines the coding guidelines and best practices we use for writing demos, code snippets, interactive examples, etc, for use on MDN. 4 | 5 | If you are looking for guidelines to follow when writing your code examples, you have come to the right place. The biggest advantage to adhering to these guidelines is that it will foster consistency across our samples and demos on MDN, which increases readability and comprehension overall. 6 | 7 | > **Note:** If you want advice on the styling of code as it appears on an MDN article, rather than the code content, see our [Writing style guide](/en-US/docs/MDN/Guidelines/Writing_style_guide#code_sample_style_and_formatting). 8 | 9 | ## Article structure 10 | 11 | This article contains general high-level best practices for writing MDN code examples. Its subarticles are as follows: 12 | 13 | - [General guidelines for all code](/en-US/docs/MDN/Guidelines/Code_guidelines/General) — both syntactical and for styling/displaying examples 14 | - [HTML guidelines](/en-US/docs/MDN/Guidelines/Code_guidelines/HTML) 15 | - [CSS guidelines](/en-US/docs/MDN/Guidelines/Code_guidelines/CSS) 16 | - [JavaScript guidelines](/en-US/docs/MDN/Guidelines/Code_guidelines/JavaScript) 17 | - [Shell prompt guidelines](/en-US/docs/MDN/Guidelines/Code_guidelines/Shell) 18 | 19 | ## General best practices 20 | 21 | This section provides quick general best practices for creating an understandable minimal code sample to demonstrate usage of a specific feature or function. 22 | 23 | Code samples need to be: 24 | 25 | - simple enough to be understandable, but 26 | - complex enough to do something interesting, and preferably useful. 27 | 28 | There is one overarching consideration that you need to keep in mind: **Readers will copy and paste the code sample into their own code, and may put it into production.** 29 | 30 | Therefore, you need to make sure that the code example is usable and follows generally accepted best practices, and **does not** do anything that will cause an application to be insecure, grossly inefficient, bloated, or inaccessible. If the code example is not runnable or production-worthy, be sure to include a warning in a code comment and in the explanatory text — if it is a snippet and not a full example, make this clear. This also means that you should provide **all** of the information necessary to run the example including any dependencies and setup. 31 | 32 | Code samples should be as self-contained and easy to understand as possible. The aim is not necessarily to produce efficient, clever code that impresses experts and has great functionality, but rather to produce reduced working examples that can be understood as quickly as possible. 33 | 34 | Further general best practices are as follows: 35 | 36 | - The sample should be short and ideally only show the feature you are immediately interested in. 37 | - **Only** include code that is essential for the example. A large amount of non-relevant code can easily distract or confuse the audience. If you want to provide a full, more lengthy, example put it in one of our [GitHub repos](https://github.com/mdn/) (or a JSBin, Codepen, or similar) and then provide the link to the full version above or below the sample. 38 | - Don't include unnecessary server-side code, libraries, frameworks, preprocessors, and other such dependencies — they make the code less portable, and harder to run and understand. Use vanilla code where possible. 39 | - Don't assume knowledge of any libraries, frameworks, preprocessors, or other non-native features. For example, use class names that make sense within the example rather than classnames that make sense to BEM or Bootstrap users. 40 | - Write your code as cleanly and understandably as possible, even if it is not the most efficient way to do it. 41 | - Don't use bad practices for brevity (such as presentational elements like {{HTMLElement("big")}} or {{domxref("Document.write", "document.write()")}}); do it correctly. 42 | - In the case of API demos, if you are using multiple APIs together point out what APIs are included, and what features come from where. 43 | 44 | 45 | <!-- Converting live sample --> 46 | MDN has a "[live sample](/en-US/docs/MDN/Structures/Live_samples)" system, where the code sample shown on a page is directly used to display the output of that same sample. However, many existing articles have code samples that do not yet use this system, and need to be converted. 47 | 48 | Live samples, which let you see what a sample's output looks like, make documentation more dynamic and instructive. This guide covers how to take existing samples and add "live" functionality to them. 49 | 50 | ## Where does it need to be done? 51 | 52 | Any article that has a static code example (just blocks of HTML, CSS, JavaScript) that you think would benefit from being shown running live. 53 | 54 | ## What do you need to know to do the task? 55 | 56 | - Understanding of HTML, CSS and/or JavaScript, depending on the code sample. 57 | - Ability to use [KumaScript](/en-US/docs/MDN/Tools/KumaScript) macros within MDN articles. 58 | 59 | ## What are the steps to do the task? 60 | 61 | 1. Find a code example that you think should be converted to be "live". 62 | 2. Convert the code sample to be "live". 63 | 3. Delete any code or image that was previously used to display the output of the sample. 64 | 65 | For more information on creating and editing Live Samples, see [Using the live sample system](/en-US/docs/MDN/Structures/Live_samples) 66 | 67 | <!-- interactive example --> 68 | When learning the web, it's important to rely on active learning content. Such content is made to help with learning something pro-actively. It can be exercises, live hackable examples, tasks to perform, assessments, etc. In short, anything that can help someone to actively understand something. 69 | 70 | There is no straightforward way to create such content. For example many third party tools exist that can help you create live hackable examples (see: [JSFiddle](https://jsfiddle.net/), [CodePen](https://codepen.io/), [Dabblet](https://dabblet.com/), etc.) that you can link from MDN articles. If you want to create more advanced comprehensible exercises, you can easily use [Thimble](https://thimble.mozilla.org) from the WebMaker project. 71 | 72 | Currently, MDN does not have an easy tool to author such active content. However, if you are a coder you can use the current MDN features to create custom active learning content. 73 | 74 | ## MDN live samples 75 | 76 | MDN has a very cool feature called **live samples**. It's a mechanism that turns any HTML, CSS, and JavaScript code inside an MDN page into its executed equivalent. Before using it, you should read over [Using the live sample system](/en-US/docs/MDN/Structures/Live_samples), which is our complete documentation for building them. While they're easy to create, there are quirks and tricks you'll learn along the way. 77 | 78 | What is interesting is that it's really easy to tweak that feature to use it in order to embed any kind of tool or utility you want into an MDN page. 79 | 80 | ### Hidden code 81 | 82 | The first way to use a code sample to create active learning content is to edit the page where you want to add your content. Use the Live Sample feature to create your content as you wish. Don't bother with the code complexity you could write; just create what you need. Once your code example is ready, surround it with a simple {{HTMLElement('div')}} element with an appropriate `id` attribute. Add the class `hidden` to any {{HTMLElement('pre')}} elements that surround this code. By doing so, your code won't be displayed but your live sample remains accessible and displayable. 83 | 84 | Let's see a simple example: 85 | 86 | Click on the following square to randomly change its color: 87 | 88 | <div id="hidden_code_example"><pre class="brush: html hidden"><div class="square"> 89 | <p class="color">#000000</p> 90 | </div></pre><pre class="brush: css hidden">body { 91 | padding: 10px; 92 | margin : 0; 93 | } 94 | 95 | .square { 96 | width : 80px; 97 | height : 80px; 98 | padding: 10px; 99 | background-color: black; 100 | color: white; 101 | text-align: center; 102 | } 103 | 104 | .color { 105 | width: 60px; 106 | text-shadow: 1px 1px 1px black; 107 | } 108 | 109 | </pre><pre class="brush: js hidden">function setColor(color) { 110 | document.querySelector('.square').style.backgroundColor = '#' + color; 111 | document.querySelector('.color').textContent = '#' + color; 112 | } 113 | 114 | function getRandomColor() { 115 | var color = Math.floor(Math.random() \* 16777215); 116 | return color.toString(16); 117 | } 118 | 119 | document.addEventListener('click', function (e) { 120 | setColor(getRandomColor()); 121 | }); 122 | 123 | </pre></div> 124 | 125 | {{EmbedLiveSample('hidden_code_example', 120, 125)}} 126 | 127 | If you take a look at the source code of this page, you'll see the following HTML code: 128 | 129 | ```html 130 | <p>Click on the following square to randomly change its color or just type an hexadecimal code color</p> 131 | 132 | <div id="hidden_code_example"> 133 | 134 | <pre class="brush: html hidden"> 135 | <div class="square"> 136 | <p class="color">#000000</p> 137 | </div> 138 | </pre> 139 | 140 | <pre class="brush: css hidden"> 141 | body { 142 | padding: 10px; 143 | margin : 0; 144 | } 145 | 146 | .square { 147 | width : 80px; 148 | height : 80px; 149 | padding: 10px; 150 | background-color: black; 151 | color: white; 152 | text-align: center; 153 | } 154 | 155 | .color { 156 | width: 60px; 157 | text-transform: uppercase; 158 | } 159 | </pre> 160 | 161 | <pre class="brush: js hidden"> 162 | function setColor(color) { 163 | document.querySelector('.square').style.backgroundColor = '#' + color; 164 | document.querySelector('.color').textContent = '#' + color; 165 | } 166 | 167 | function getRandomColor() { 168 | var color = Math.floor(Math.random() * 16777215); 169 | return color.toString(16); 170 | } 171 | 172 | document.addEventListener('click', function (e) { 173 | setColor(getRandomColor()); 174 | }); 175 | </pre> 176 | </div> 177 | 178 | \{{EmbedLiveSample('hidden_code_example', 120, 125)}} 179 | ``` 180 | 181 | You can see a more advanced example of such a tweak on [the Canvas API page](/en-US/docs/Web/API/Canvas_API#javascript). 182 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/page-structure/images-media/index.md: -------------------------------------------------------------------------------- 1 | 2 | <!-- Captured --> 3 | 4 | 5 | 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. 6 | This article discusses when including videos in MDN articles is appropriate, and provides tips on how to create simple but effective videos on a budget. 7 | 8 | ## When to use video on MDN 9 | 10 | There are several arguments against using video content for technical documentation, particularly reference material and advanced level guides: 11 | 12 | - Video is linear. 13 | People don't tend to read online documentation in a linear fashion, starting at the start and reading through to the end. 14 | _They scan._ 15 | Video is really hard to scan — it forces the user to consume the content start-to-finish. 16 | - Video is less information-dense than text. 17 | It takes longer to consume a video explaining something than it does to read the equivalent instructions. 18 | - Video is big in terms of file size, and therefore more expensive and less performant than text. 19 | - Video has accessibility problems: it's more expensive to produce generally than text, but especially to localize, or make usable by screen reader users. 20 | - Following on from the last point, video is much harder to edit/update/maintain than text content. 21 | 22 | > **Note:** It's worth keeping these problems in mind, even when you are making videos, so you can try to alleviate some of them. 23 | 24 | There are many popular video sites that provide a lot of video tutorials. 25 | MDN isn't a video-driven site, but video does have a place on MDN in certain contexts. 26 | 27 | We tend to most commonly use video when describing some kind of instruction sequence or multi-step workflow that would be hard to describe concisely in words: _"do this, then do that, then this will happen"_. 28 | It is especially useful when trying to describe processes that cross over multiple applications or windows, and include GUI interactions that might not be simple to describe: _"now click on the button near the top-left that looks a bit like a duck"_. 29 | 30 | In such cases it is often more effective to just **show** what you mean. 31 | We most commonly use videos when explaining features of the [Firefox DevTools](https://firefox-source-docs.mozilla.org/devtools-user/index.html). 32 | 33 | ## What should MDN videos look like? 34 | 35 | Videos for MDN should be: 36 | 37 | - **Short**: Try to keep videos under 30 seconds, ideally under 20 seconds. 38 | This is short enough not to make big demands on peoples' attention spans. 39 | - **Simple**: Try to make the workflow simple, 2-4 distinct pieces. 40 | This makes them easier to follow. 41 | - **Silent**: Audio makes videos much more engaging, but they are much more time-consuming to make. 42 | Also, having to explain what you're doing makes the videos much longer, and adds to the costs (both financial and in terms of time) of localization. 43 | 44 | To explain something more complex, you can use a blend of short videos and screenshots, interspersed with text. 45 | The text can help reinforce the points made in the video, and the user can rely on the text or the video as they choose. 46 | See [Working with the Animation Inspector](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/work_with_animations/index.html#animation-inspector) for a good example. 47 | 48 | In addition, you should consider the following tips: 49 | 50 | - The video will end up being uploaded to YouTube before embedding. 51 | We'd recommend a 16:9 aspect ratio for this use, so that it fills up the entire viewing frame and you don't end up with ugly black bars on the top and bottom (or left and right) of your video. 52 | So for example, you might choose a resolution of 1024×576, 1152×648, or 1280×720. 53 | - Record the video in HD, so that it looks better when uploaded. 54 | - For DevTools videos, it is often a good idea to choose a contrasting theme to the page content, for example choose the dark theme if the example webpage is light-themed. 55 | It is easier to see what is going on, and where the DevTools start and the page ends. 56 | - For DevTools videos, zoom in the DevTools as much as you can while still showing everything you want to show and making it look OK. 57 | - Make sure the thing you are trying to demonstrate isn't covered up by the mouse cursor. 58 | - Consider whether or not it would be useful to configure the screen recording tool to add a visual indicator of mouse clicks. 59 | 60 | ## Video tools 61 | 62 | You'll need some kind of a tool for recording the video. 63 | These range from free to expensive, and simple to complex. 64 | If you are already experienced in creating video content, then great. 65 | If not, then we'd recommend that you start with a simple tool and then work up to something more complex if you start to enjoy creating video and want to create more interesting productions. 66 | 67 | The following table provides some recommendations for good starter tools. 68 | 69 | | Tool | OS | Cost | Post-production features available? | 70 | | ------------------------- | --------------------- | ------ | ----------------------------------- | 71 | | Open Broadcaster Software | macOS, Windows, Linux | Free | Yes | 72 | | CamStudio | Windows | Free | Limited | 73 | | Camtasia | Windows, macOS | High | Yes | 74 | | QuickTime Player | macOS | Free | No, just allows simple recording | 75 | | ScreenFlow | macOS | Medium | Yes | 76 | | Kazam | Linux | Free | Minimal | 77 | 78 | ### QuickTime tips 79 | 80 | If you are using macOS, you should have QuickTime Player available. 81 | This actually provides pretty easy simple recording facilities too: 82 | 83 | 1. Choose _File_ > _New Screen Recording_ from the main menu. 84 | 2. In the _Screen Recording_ box, hit the record button (the red round button). 85 | 3. Drag a rectangle round the area of the screen you want to record. 86 | 4. Press the _Start Recording_ button. 87 | 5. Perform whatever actions you want to record. 88 | 6. Press the _Stop_ button. 89 | 7. Choose _File_ > _Export As..._ > _1080p_ from the main menu to save as hi definition. 90 | 91 | ### Other resources 92 | 93 | - [How to Add Custom Callouts to Screencast Videos in Screenflow](https://photography.tutsplus.com/tutorials/how-to-add-custom-callouts-to-screencast-videos-in-screenflow--cms-27122) 94 | 95 | ## A workflow for creating videos 96 | 97 | the following subsections describe the general steps you'd want to follow to create a video and get it shown on an MDN page. 98 | 99 | ### Preparation 100 | 101 | First, plan the flow you want to capture: consider the best points to start and end. 102 | 103 | Make sure the desktop background and your browser profile are clean. 104 | Plan the size and positioning of browser windows, especially if you will be using multiple windows. 105 | 106 | Plan carefully what you are actually going to record, and practice the steps a few times before recording them: 107 | 108 | - Don't start a video in the middle of a process — consider whether the viewer has enough context for your actions to make sense to them. 109 | In a short DevTools video for example, it is a good idea to start by opening the DevTools to allow the viewer to get oriented. 110 | - Consider what your actions are, slow down, and make them obvious. 111 | Whenever you have to perform an action (say, click an icon), take it slow and make it obvious, so for example: 112 | 113 | - Move the mouse over the icon 114 | - Highlight or zoom (not always, depending on whether it feels needed) 115 | - Pause for a beat 116 | - Click the icon 117 | 118 | - Plan zoom levels for the parts of the UI that you're going to show. 119 | Not everyone will be able to view your video in high definition. 120 | You will be able to zoom particular parts in post-production, but it's a good idea to zoom the app beforehand as well. 121 | 122 | > **Note:** Don't zoom so far that the UIs you are showing start to look unfamiliar or ugly. 123 | 124 | ### Recording 125 | 126 | When recording the workflow you want to show, go through the flow smoothly and steadily. 127 | Pause for a second or two when you are at key moments — for example, about to click on a button. 128 | Make sure the mouse pointer doesn't obscure any icons or text that are important to what you are trying to demonstrate. 129 | 130 | Remember to pause for a second or two at the end, to show the result of the flow. 131 | 132 | > **Note:** If you are using a really simple tool like QuickTime Player and post production is not an option for some reason, you should get your windows set up in the right size to show the area you want to show. In the Firefox DevTools, you can use the [Rulers Tool](https://firefox-source-docs.mozilla.org/devtools-user/rulers/index.html) to make sure the viewport is at the right aspect ratio for the recording. 133 | 134 | ### Post-production 135 | 136 | You'll be able to highlight key moments in post-production. 137 | A highlight can consist of a couple of things, which you'll often combine: 138 | 139 | - Zoom in on parts of the screen. 140 | - Fade the background. 141 | 142 | Highlight key moments of the workflow, especially where the detail is hard to see: clicking on a particular icon or entering a particular URL, for example. 143 | Aim for the highlight to last for 1-2 seconds. 144 | It's a good idea to add a short transition (200-300 milliseconds) at the starts and ends of the highlights. 145 | 146 | Use some restraint here: don't make the video a constant procession of zooming in and out, or viewers will get seasick. 147 | 148 | Crop the video to the desired aspect ratio, if required. 149 | 150 | ### Uploading 151 | 152 | Videos currently have to be uploaded to YouTube to be displayed on MDN, for example the [mozhacks](https://www.youtube.com/user/mozhacks/videos) channel. 153 | Ask a member of MDN staff to upload the video if you don't have somewhere appropriate to put it. 154 | 155 | > **Note:** Mark the video as "unlisted" if it doesn't make sense out of the context of the page (if it's a short video, then it probably doesn't). 156 | 157 | ### Embedding 158 | 159 | Once uploaded, you can embed the video in the page using the [`EmbedYouTube`](https://github.com/mdn/yari/blob/main/kumascript/macros/EmbedYouTube.ejs) macro. 160 | This is used by inserting the following in your page at the position you want the video to appear: 161 | 162 | ``` 163 | \{{EmbedYouTube("you-tube-url-slug")}} 164 | ``` 165 | 166 | The single property taken by the macro call is the string of characters at the end of the video URL, not the whole URL. 167 | For example, the video embedded in our [Page inspector 3-pane mode](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/3-pane_mode/index.html) article is available at https\://www\.youtube.com/watch?v=ELS2OOUvxIw, so the required macro call looks like this: 168 | 169 | ``` 170 | \{{EmbedYouTube("ELS2OOUvxIw")}} 171 | ``` 172 | -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/pull-requests/index.md: -------------------------------------------------------------------------------- 1 | # Pull requests 2 | 3 | # Reviewing pull requests 4 | 5 | This document describes the review process for content changes on MDN Web Docs, and is for use by those who have been tasked with reviewing MDN content PRs. 6 | 7 | ## Process for reviewing content changes 8 | 9 | Content changes we get on MDN are related to a variety of work streams, 10 | for example: 11 | 12 | - Day-to-day content improvement work — new APIs, new CSS properties, and 13 | other significant platform updates and content additions, usually done 14 | by MDN staff working for Mozilla, Google, Open Web Docs, Samsung, etc., 15 | but also sometimes by community volunteers. 16 | - "Drive-by fixes" — small updates done to the site to fix typos, grammatical issues, and technical inaccuracies, usually as they are found by readers of MDN Web Docs. 17 | - MDN content bug fixes, usually done by volunteers to close issues on this repo. 18 | 19 | Regardless of how a content change is done, they will be submitted as 20 | [pull requests](https://github.com/mdn/content/pulls) on this repo, which will require rapid reviewing and merging to ensure that the site does not get out-of-date. This is being handled as follows: 21 | 22 | 1. Different MDN staff members and volunteers have been assigned as "topic 23 | review owners", meaning that when a pull request comes in related to a 24 | particular topic area of the site (e.g. the CSS reference, or the learning area), it will be assigned to that area's topic review owner(s) and they will receive an e-mail notification asking for a review. This is being handled using a [CODEOWNERS](https://github.com/mdn/content/blob/main/.github/CODEOWNERS) file, in which particular content directories are assigned to the topics review owner's GitHub usernames. 25 | 1. Once the review has been done and the pull request has been approved, the 26 | reviewer should also merge the pull request. 27 | 1. The site will be rebuilt once every 24 hours to ensure that the content 28 | does not get too stale. 29 | 30 | ## Review guidelines 31 | 32 | If you are reviewing mdn content changes, read through the following 33 | guidelines. There’s quite a lot here, but don’t worry if you don’t review 34 | perfectly in accordance with all of these points immediately. It is more 35 | important to make sure the content is readable, useful, correct, and not 36 | inappropriate, than it is to follow every guideline to the letter. 37 | 38 | 1. Familiarize yourself with the [MDN Code example guidelines](../../how-to-write/writing-style-guide/code-example-guidelines/index.md) and make sure that code examples follow the guidelines. You’ll get used to them eventually, and we are intending to automatically lint against our guidelines at some point in the future. 39 | 1. Familiarize yourself with the [MDN Writing style guide](../../how-to-write/writing-style-guide/index.md), and use it to inform your reviews of new text content. 40 | 1. Familiarize yourself with the MDN [pull request guidelines](https://github.com/mdn/content/blob/main/README.md#pull-request-etiquette). 41 | The key points here are 42 | - You have the right to request more information to help your review if the submitter has not explained why they are making this change. 43 | - You have the right to close a pull request if it is too complex and/or contains multiple unrelated changes and ask the submitter to submit their changes in smaller atomic chunks. 44 | 1. When reviewing a pull request, use the [GitHub review tools](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews). Use "Request changes" when submitting a review that will require the submitter to do some more work, or "Approve" if the submission is ready to add and you want to merge it. [Reviewing proposed changes in a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) is also useful if you want more information. 45 | 1. Be polite and constructive at all times when writing review comments, or otherwise interacting with the submitter and other community members. We are all bound by [our Code of Conduct](CODE_OF_CONDUCT.md) when contributing to MDN, which means adhering to Mozilla's [Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/). If anyone has engaged in behavior that is potentially illegal or makes you or someone else feel unsafe, unwelcome, or uncomfortable, you are encouraged to [report it](https://www.mozilla.org/en-US/about/governance/policies/participation/reporting/). We want MDN to be a welcoming, friendly community that we can all be proud of. 46 | 1. If a pull request is fine apart from a small typo or some other minor issue, you might want to just fix the issue yourself rather than ask the submitter to change it. You can do this provided the PR has been set up to allow changes (see [Allowing changes to a pull request branch created from a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) for more details). If you are not sure how to make changes to someone else’s pull request, [@vkWeb](https://github.com/vkWeb/) wrote some nice simple instructions on how to do this on the command line; see [ReviewPRCommands](https://gist.github.com/vkWeb/dcec82b079f1edc19478ddb58b0ffc5e). 47 | - Alternatively, you can edit files using the GitHub UI — go to the pull request’s "Files changed" tab, find the file you want to edit, and choose "three dot" menu (...) > Edit file. 48 | 1. If you don’t understand a content change that you’ve been selected to review, or feel that it is too large and complex for you to deal with, don’t panic! Feel free to reach out to someone else to ask for help, like a colleague, or someone else in your group of topic review owners (if you know who they are). If you are not sure who to approach for help, then ping our `@core-yari-content` group to ask for help. 49 | 1. Related to the above point, it is rare that you’ll be required to review a large, complex content change with no warning, like a complete page rewrite, or the addition of several new reference pages or tutorials. Usually such changes are done as part of specific work streams where the content has been approved for addition, and reviewer(s) have been assigned already. In such cases, the PR should be linked to an issue that explains all these details. If you are not sure, ask the submitter if they need a review of the content, and where the rationale behind the change is explained. Ping our team on [MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) to ask for help if you are still not sure, or if you think the content is suspicious. 50 | 51 | Note: You may encounter merge conflicts as you review pull requests, if a another pull request that touches some of the same files got merged before the one you are reviewing. [Addressing merge conflicts](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts) is a useful resource to help you. Feel free also to ask your team(s) for help if you need it. 52 | 53 | ## Specific reviewer overrides on pull requests 54 | 55 | Some of the pull requests submitted on the `content` repo relate to specific workstreams being undertaken by browser vendors or other organizations that have a defined set of writers and reviewers. In these cases, the submitter of the PR will include the username of the reviewer in a line at the bottom of the pull request description, for example: 56 | 57 | `reviewer: @jpmedley` 58 | 59 | Upon submitting the pull request, they will request a review from the reviewer specified in the pull request description. Once that reviewer has approved the new content, they will then ask you for an approval as required by the `CODEOWNERS` system for the pull request to be mergeable. 60 | 61 | Therefore, if you receive a pull request review request and then see that you have been overridden with another reviewer in the manner described above, then don't review the pull request — just wait for an approval request. 62 | 63 | ## Topic review owners 64 | 65 | The following specific topic areas are being reviewed by the kind souls listed underneath them. Be kind to them, and thank them for all the help they give to this project. If you would like to help with MDN content reviews, 66 | [get in touch with us](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Getting_started#Step_4_Ask_for_help). 67 | 68 | Note that changes to any content areas not explicitly listed below will be handled by the [@core-yari-content](https://github.com/orgs/mdn/teams/core-yari-content) team. 69 | 70 | - [Web accessibility content](https://github.com/orgs/mdn/teams/yari-content-accessibility) 71 | - [General learning content](https://github.com/orgs/mdn/teams/yari-content) 72 | - [CSS learning content](https://github.com/orgs/mdn/teams/yari-content-css) 73 | - [Server-side learning content](https://github.com/orgs/mdn/teams/yari-content) 74 | - [MDN meta docs](https://github.com/orgs/mdn/teams/yari-content) 75 | - [Firefox Developer Tools content](https://github.com/orgs/mdn/teams/yari-content) 76 | - [Mozilla Add-ons reference content](https://github.com/orgs/mdn/teams/yari-content-mozilla-add-ons) 77 | - [HTTP reference content](https://github.com/orgs/mdn/teams/yari-content-http) 78 | - [CSS reference content](https://github.com/orgs/mdn/teams/yari-content-css) 79 | - [HTML reference content](https://github.com/orgs/mdn/teams/yari-content-html) 80 | - [JavaScript reference content](https://github.com/orgs/mdn/teams/yari-content-javascript) 81 | - [Web API reference content](https://github.com/orgs/mdn/teams/yari-content-web-api) 82 | - [SVG reference content](https://github.com/orgs/mdn/teams/yari-content-svg) 83 | - [WebAssembly reference content](https://github.com/orgs/mdn/teams/content-webassembly) 84 | 85 | ### Reviewer alumni 86 | 87 | The following folks used to be in one or more of our review teams, but no 88 | longer have the time to contribute; we want to give them our sincere thanks 89 | for all their help. 90 | 91 | - [@vkWeb](https://github.com/vkWeb/) 92 | - [@ericwbailey](https://github.com/ericwbailey) 93 | - [@chrisdavidmills](https://github.com/chrisdavidmills/) 94 | - [@mirunacurtean](https://github.com/mirunacurtean) 95 | 96 | ## Make progress, not noise 97 | 98 | Think carefully about the way you handle communication in the project — make sure it is useful, and that it doesn’t make other contributors jobs harder. Submitting pull requests to fix issues is great, but are they truly useful, and easy to review? Filing issues and joining in other conversations is fine, but are your issues and comments on topic, or are they just adding noise? 99 | 100 | As a rule, do: 101 | 102 | - Fix one issue per PR — it may be slightly more work for you, but it is much easier to review a single clear fix. 103 | - Ask questions using other mechanisms like [chat rooms](https://chat.mozilla.org/#/room/#mdn:mozilla.org) or [forums](<(https://discourse.mozilla.org/c/mdn/236)>) if you are not sure whether something is useful or have a simple question. 104 | - Read the [contributor documentation]() and [how to write documentation]() first to try to answer the question yourself before filing a pr. 105 | 106 | Don’t: 107 | 108 | - 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). 109 | 110 | ## Opening a pull request 111 | 112 | ## Reviewing a pull request 113 | 114 | ## Pull requests we accept 115 | 116 | ## `idle` pull requests 117 | -------------------------------------------------------------------------------- /contrib-docs/community-guidelines/open-source-etiquette/index.md: -------------------------------------------------------------------------------- 1 | # Open-source etiquette 2 | 3 | If you've not worked on an open-source project (OSP) before, it is a good idea to read this article before starting to contribute to MDN Web Docs (or other open-source projects). If you adopt the best practices outlined here, it will help ensure that you and the other project contributors feel valued and safe and stay productive. 4 | 5 | This article won't teach you everything about contributing to open source; the aim here is to give you some good starting points to think about as you get started with open-source contributions. 6 | 7 | ## Be clear about your reason for contributing to an OSP 8 | 9 | Before you start contributing to an open-source project, ask yourself why you want to do that. It is fine if the answer to this question is just "I'm bored and I want to find something productive to do with my time", but you can probably go deeper than that. 10 | 11 | Even better reasons might include: 12 | 13 | - I use this tool all the time and want to help make it better. Or I found a bug in the tool and want to fix it. 14 | - I want to help other people use the tool more successfully. 15 | - I want to help other people contribute to the project more successfully. 16 | - I want to improve my skills. 17 | - I want to publicly demonstrate my skills as part of my college or university course. 18 | - I want to publicly demonstrate my skills to improve my chances of getting a job. 19 | 20 | Some of these reasons are self-serving, and that's OK. If you're spending your time working on a project for free, then it is fair to expect to get something out of it. In addition, having a clear set of reasons for contributing will make it easier to decide what to work on first. 21 | 22 | Some not-so-good reasons to start contributing are: 23 | 24 | - I want someone to talk to. 25 | - I want some people to troll/boss around. 26 | - I want to show off how amazing I am. 27 | 28 | Your presence on the project should be productive, and it shouldn't stop others from being so too. 29 | 30 | ## Be mindful of the language you use 31 | 32 | This is our top advice for anyone starting open-source contributions: Be polite and kind and avoid incendiary or offensive language. We could abbreviate this to "be kind". Be kind to the other contributors on the project, and it will be a happier and more productive place. 33 | 34 | Some etiquettes around this include: 35 | 36 | - Thanking people if they help you. 37 | - Congratulating people where appropriate (for example, when they land their first pull request or fix a particularly difficult bug). 38 | - Always responding respectfully to people, even if you feel like the answer to their question was a bit obvious or that they are repeating themselves. 39 | - Trying to help people to do better next time, in a supportive way, e.g., during pull request reviews or as you answer their questions. Saying "this is wrong" or "here is the answer" is nowhere near as helpful as saying "This is OK, but I feel that this would be better if you tried doing it more like this. Here's a blog post for more ideas" or "You can find the answer here; also check out this link for more common answers". 40 | 41 | You and other contributors are (or should be) here because you all want to make a positive contribution to the project, but beyond that, you can't assume anything about them. This includes their: 42 | 43 | - Knowledge of the project and the technologies used to build it 44 | - Gender, sexuality, age, languages spoken, location, political views, religion, or other personal attributes 45 | - Experience with open-source projects 46 | - Confidence 47 | - Expectations 48 | - Sense of humor 49 | 50 | You should, therefore, as far as possible stay focused on the topic and stay away from potentially controversial off-topic subjects like religion or politics. Be mindful of being supportive and respectful even if you disagree with someone or don't like a decision they've made. 51 | 52 | Also, you should refrain from any swearing / using offensive language on MDN, even if it is not directed at anyone in particular. It is not needed for participation, and some people are really sensitive to it. 53 | 54 | Be aware that there are rules in place in any good OSP to protect its contributors against being made to feel uncomfortable while contributing. This usually comes in the form of a CODE_OF_CONDUCT.md file on GitHub. 55 | 56 | For example, MDN's repos are governed by the wide-reaching [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/). Mildly offensive behavior on MDN repos (such as constantly being off-topic, disruptive, or rude) will usually be first responded to by a warning on the repo, followed by a final warning, then a temporary or permanent ban. More serious behavioral problems such as hate speech or threats against another contributor will not be tolerated and will likely result in an instant ban. 57 | 58 | If you face any situation on MDN that makes you feel uncomfortable, you should always report it using the mechanism provided in the code of conduct. 59 | 60 | ## Choose effective contributions 61 | 62 | Think about what you want to do on the project. For example, we have a large list of issues filed at <https://github.com/mdn/content/issues>, categorized by various GitHub labels into estimated time to fix, technology categories, and more. Another good label to look for is "good first issue", which is generally given to issues that are quite simple and good for beginners to get started with. We are also soon going to start triaging our issues more extensively, by adding other labels such as priority indicators. Try picking some issues that you think you can manage with the time you have available, and ask to be assigned to them. 63 | 64 | You could also contribute by opening pull requests to fix problems that you come across while reading articles on MDN Web Docs. 65 | 66 | A lot of the work on MDN Web Docs revolves around writing documentation and code examples, but there are other ways to contribute too, including: 67 | 68 | - Triaging issues that come in. 69 | - Fixing typos. 70 | - Improving grammar and making pages more understandable. 71 | - Mentoring people who are trying to fixe issues. 72 | 73 | Every fix is useful, no matter how small, and we won't turn any fix away. Nevertheless, try to make sure your fixes are productive. We'd like to advise against these kinds of contributions: 74 | 75 | - Updating code styling just because "you like that style better". 76 | - Updating language style "just because you like that style better". 77 | - Changing pages from US English to British English. 78 | - Adding or removing a bunch of punctuation when there's nothing wrong. 79 | - Changing the testing framework we are using for something else because you prefer it. 80 | 81 | In many cases, things are like they are on OSPs for a reason. You should read their style guides if they have one. When in doubt about whether or not a fix is productive, always ask first! 82 | 83 | ## Read the manual 84 | 85 | Good OSPs will always make contributor documentation readily available. On GitHub projects, it is usually in the repo's CONTRIBUTING.md file, or sometimes in the project's README.md file. Being a documentation project, MDN content has a [README](https://github.com/mdn/content/blob/main/README.md) and a decent set of contributor docs on the site itself (see [Contributing to MDN Web Docs](/en-US/docs/MDN/Contribute)). <!--might need to update text or link--> 86 | 87 | Don't be afraid to ask for help, but ALWAYS try to find the answer to your question first before asking. This way, you build up your knowledge of the project, become more independent, and don't put an unnecessary burden on the other contributors. 88 | 89 | Of course, the documentation won't always be perfect. If an explanation is hard to find or not described very well, file an issue, or create a pull request to try to fix it yourself. 90 | 91 | ## Find out where to ask questions 92 | 93 | Always find out the best place to ask questions. Good OSPs will always make this clear in their docs (see [ask for help on MDN](/en-US/docs/MDN/Contribute/Getting_started#step_4_ask_for_help)). If you want to ask general questions, always make use of these channels. Don't just file an issue on GitHub for every question because it adds noise to the project (see "Make progress, not noise" below). <!--link to be revisited--> 94 | 95 | ## Make progress, not noise 96 | 97 | Think carefully about the way you handle communication in the project — make sure it is useful, and that it doesn't make other contributors' jobs harder. Submitting pull requests to fix bugs is great, but are they truly useful and easy to review? Filing issues and joining in other conversations is fine, but are your issues and comments on-topic, or are they just adding noise? 98 | 99 | As a rule, do: 100 | 101 | - Discuss one topic per issue so that it is easy to keep issues focused and productive. 102 | - Fix one issue per PR. It may be slightly more work for you, but it is much easier for reviewers to review a single clear fix. 103 | - Contribute to other threads if you have a useful point to make or can answer someone else's question. 104 | - Ask questions using other mechanisms like chat rooms or forums if you are not sure whether or not something is useful or if you have a simple question. 105 | - Read the manual first to try to answer the question yourself before asking it. 106 | 107 | Don't: 108 | 109 | - Complicate issues by trying to discuss multiple topics at once or by making off-topic comments. 110 | - 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). 111 | - Open lots of issues asking vague questions. 112 | - Ask questions without trying to solve the problem yourself first. 113 | 114 | ## OSPs are a democracy (almost) 115 | 116 | OSPs are quite democratic — many decisions are voted on. You are largely free to contribute how you want, as long as you don't impede anyone else from contributing. 117 | 118 | However, changes in some topics and areas will still be decided by a small group of core contributors. You are free to make a case against any decision, but sometimes a moderator will make a call that goes against your opinion. You need to respect and accept these decisions. 119 | 120 | It is useful to get to know any project's moderators, so you know who best to ask for help in pull requests or issue threads. 121 | 122 | ## Be patient and timely 123 | 124 | Bear in mind that many people working on OSPs are doing it in their free time, without payment, and everyone working on OSPs is generally very busy. If you are waiting for something like a pull request review or an answer to a question, be patient. 125 | 126 | It is reasonable to wait for a few days and then ping someone politely to ask if they've had the time to look at it. If they happen to be too busy, it may be best to wait a further week and try following up with them then. 127 | 128 | It is NOT reasonable to start demanding things, like a quick reply. 129 | 130 | If someone is waiting for you to do something for them, you should be extended the same courtesy, but at the same time, try to respond as promptly as you can. If you really can't find the time, let them know, and ask the maintainers to help you find someone else to do the task. 131 | 132 | ## See also 133 | 134 | - [How to contribute to open source](https://opensource.guide/how-to-contribute/) 135 | - [More general freeCodeCamp "How to contribute to open source" list](https://github.com/freeCodeCamp/how-to-contribute-to-open-source) 136 | - [Getting started with contributing to open source](https://stackoverflow.blog/2020/08/03/getting-started-with-contributing-to-open-source/) 137 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/what-we-write/experimental_deprecated_obsolete/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Experimental, deprecated and obsolete' 3 | slug: MDN/Writing_guide/Experimental_deprecated_obsolete 4 | page-type: mdn-writing-guide 5 | tags: 6 | - meta 7 | - writing-guide 8 | --- 9 | 10 | {{MDNSidebar}} 11 | 12 | ## Terms used on MDN Web Docs to label a technology 13 | 14 | <!--content copied from /en-us/mdn/guidelines/conventions_definitions --> 15 | 16 | These terms are commonly associated with technologies and specifications. These are also defined in our [Browser compatibility project](https://github.com/mdn/browser-compat-data/blob/main/schemas/compat-data-schema.md#status-information). 17 | 18 | ### Deprecated 19 | 20 | The term **deprecated** on MDN Web Docs is used to mark an API or technology that is no longer recommended. A deprecated API or technology might be removed in the future or might only be kept for compatibility purposes and may still work. We recommend to avoid using the functionality marked as deprecated. 21 | 22 | ### Obsolete 23 | 24 | On MDN Web Docs, the term **obsolete** was used to mark an API or technology that is not only no longer recommended but is also no longer implemented in browsers. The term was, however, confusing. It was similar to **deprecated** but it's distinction from **deprecated** ws not very helpful. 25 | 26 | > **Note:** We do not use the term **obsolete** on MDN Web Docs anymore. If you come across any instances, they should be removed or replaced with the term **deprecated**. 27 | 28 | ### Experimental 29 | 30 | The term **experimental** can mean different things depending on the context you hear or read it in. 31 | When a technology is described as experimental on MDN Web Docs, it means that the technology is nascent and immature and is currently _in the process_ of being added to the web platform (or being considered for addition). 32 | 33 | For a technology that's marked **experimental**, one or both of the following conditions will be true: 34 | 35 | - It is implemented and enabled by default in _less than two_ modern major browsers. 36 | - Its defining specification is likely to change significantly, in backwards-incompatible ways (i.e., it may break existing code that relies on the feature). 37 | 38 | If one or both of these conditions is true, then you should think carefully before you start using that technology in any kind of production project (i.e., a project that is not just a demo or experiment). On the other hand, as a web developer, you can try out a feature that is marked **experimental** and provide feedback to browser vendors and standards authors. <!--taken from https://github.com/mdn/browser-compat-data/blob/main/schemas/compat-data-schema.md#status-information --> 39 | 40 | Conversely, a technology is no longer considered **experimental** if one of the following conditions is true: 41 | 42 | - It is implemented in two or more major browsers. 43 | - Its defining specification is unlikely to change in ways that will break the web. 44 | 45 | Usually, if a technology is supported across several major browsers, the specification will be stable, but this is not always the case. 46 | And some technologies might have a stable specification and be well-used but might not have native support in browsers ([IMSC](/en-US/docs/Related/IMSC), for example). <!-- need to revisit link --> 47 | 48 | A feature or technology that is not marked **experimental** or **deprecated** is said to be on a **standards track**, meaning the feature is part of an active specification or specification process. 49 | 50 | Sometimes during the development of a new specification or over the course of the evolution of living standards such as HTML, new elements, methods, properties, and so forth are added to the specification, kept there for a while, and then removed. Sometimes this happens very quickly, and sometimes these new items remain in the specification for months or even years before being removed. This can make it tricky to decide how to handle the removal of the item from the specification. 51 | 52 | Here are some guidelines to help you decide what to do when something is removed from the specification. 53 | 54 | > **Note:** For the purposes of this discussion, the word "item" is used to mean anything that can be part of a specification: an element or an attribute of an element, an interface or any individual method, a property, or other member of an interface, and so forth. 55 | 56 | 57 | ### If the item was never implemented 58 | 59 | If the item was _never_ implemented in a release version of _any_ browser, not even behind a preference or a flag, delete any references to the item from the documentation. 60 | 61 | - If the item has any documentation pages describing only that one item (such as {{domxref("RTCPeerConnection.close()")}}), delete that page. 62 | If the removed item is an interface, this means removing any subpages describing the properties and methods on that interface as well. 63 | - Remove the item from any lists of properties, attributes, methods, and so forth. For methods of an interface, for example, this means to remove it from the "Methods" section on the interface's overview page. 64 | - Search the text of the overview page for that interface, element, etc., for any references to the removed item. Remove those references, being sure not to leave weird grammar issues or other problems with the text. This may mean not just deleting words but rewriting a sentence or paragraph to make more sense. It may also mean removing entire sections of content if the description of the item's use is lengthy. 65 | - Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Remove those references, being sure not to leave weird grammar issues or other problems with the text. This may mean not just deleting words but rewriting a sentence or paragraph to make more sense. It may also mean removing entire sections of content if the description of the item's use is lengthy. 66 | - Search MDN Web Docs for references to the removed item, in case there are discussions elsewhere. It's unlikely that there are, since if it was never implemented, it's unlikely to be widely discussed. Remove those mentions as well. 67 | - If the [Browser compatibility data repository's](https://github.com/mdn/browser-compat-data) JSON files contain data for the removed items, delete those objects from the JSON code and submit a PR with that change, explaining the reason in the commit message and the PR description. Be careful to check that you don't break the JSON syntax while doing this. 68 | 69 | ### If the item was implemented in a browser behind a flag 70 | 71 | If the item was implemented in any release version of any one or more browsers but _only_ behind a preference or a flag, do not delete the item from the documentation immediately. Instead, mark the item as **deprecated** as follows: 72 | 73 | - If the item has any documentation pages describing only that one item (such as {{domxref("RTCPeerConnection.close()")}}), add the [`deprecated_header`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Header.ejs) macro to the top of the page and add the {{tag("Deprecated")}} tag to the page's list of tags. 74 | - On the overview page for the element, interface, or API, find the list of items that includes the item that's been removed from the specification and add the [`deprecated_inline`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Inline.ejs) macro after the item's name in that list. 75 | - Search the informative text of the overview page for that interface, element, etc., for any references to the removed item. Add warning boxes in appropriate places with text along the lines of "\[item] has been removed from the specification and will be removed from browsers soon. See \[link to page] for a new way to do this." 76 | - Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Add similar warnings. 77 | - Search MDN Web Docs for references to the removed item, in case there are discussions elsewhere. Add similar warning boxes there as well. 78 | - At some point in the future, a decision may be made to actually remove the item from the documentation; we don't normally do this but if the item was especially unutilized or uninteresting, we may decide to do so. 79 | - Update any relevant entries in the [Browser Compatibility Data repo](https://github.com/mdn/browser-compat-data) to reflect the obsolescence of the item(s) affected. 80 | 81 | ### If the item was implemented in a browser without a flag 82 | 83 | If the item was implemented in one or more release builds of browsers without requiring a preference or a flag, mark the item as **deprecated**, as follows: 84 | 85 | - If the item has any documentation pages describing only that one item (such as {{domxref("RTCPeerConnection.close()")}}), add the [`deprecated_header`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Header.ejs) macro to the top of the page and add the {{tag("Deprecated")}} tag to the page's list of tags. 86 | - On the overview page for the element, interface, or API, find the list of items that includes the item that's been removed from the specification and add the [`deprecated_inline`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Inline.ejs) macro after the item's name in that list. 87 | - Search the informative text of the overview page for that interface, element, etc., for any references to the removed item. Add warning boxes in appropriate places with text along the lines of "\[item] has been removed from the specification and is deprecated. It may be removed from browsers in the future, so you should not use it. See \[link to page] for a new way to do this." 88 | - Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Add similar warnings. 89 | - Search MDN Web Docs for references to the removed item, in case there are discussions elsewhere. Add similar warning boxes there as well. 90 | - It's unlikely that these items will be removed from the documentation anytime soon, if ever. 91 | - Update any relevant entries in the [Browser compatibility data repository](https://github.com/mdn/browser-compat-data) to reflect the deprecation of the item(s) affected. 92 | 93 | Please use common sense with wording of warning messages and other changes to the text suggested in the guidelines above. 94 | Different items will require different wording and handling of the situation. 95 | When in doubt, feel free to ask for advice on the [MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) on [Matrix](https://wiki.mozilla.org/Matrix), or on the [MDN Web Docs discussion forum](https://discourse.mozilla.org/c/mdn). 96 | 97 | ## How to communicate a specification conflict 98 | 99 | Sometimes, but rarely, there might be a conflict between different specification versions (usually W3C versus WHATWG). For example, one version might have a feature listed as deprecated, while the other doesn't. 100 | In such cases, consider what the reality is, that is, consider what browsers are actually doing, and write an "important" note to summarize that latest status. 101 | For example, as of Jan 2019, the [`inputmode`](/en-US/docs/Web/HTML/Global_attributes/inputmode) global attribute has a conflict, which was summarized like so: <!--this warning example for spec conflict does not exist anymore on that page. couldn't find any other examples as well --> 102 | 103 | > **Warning:** Specification conflict: The WHATWG specification lists `inputmode`(https://html.spec.whatwg.org/multipage/interaction.html#attr-inputmode) and modern browsers are working towards supporting it. 104 | > The [W3C HTML 5.2 spec](https://html.spec.whatwg.org/multipage/index.html#contents), however, no longer lists it (i.e. marks it as obsolete). 105 | > You should consider the WHATWG definition as correct, until a consensus is reached. 106 | 107 | 108 | 109 | 110 | 111 | 112 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/what-we-write/inclusion-criteria/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Inclusion criteria 3 | slug: MDN/Writing_guide/Inclusion_criteria 4 | page-type: mdn-writing-guide 5 | tags: 6 | - meta 7 | - writing-guide 8 | --- 9 | 10 | {{MDNSidebar}} 11 | 12 | This describes, in detail, criteria for content to be included on MDN Web Docs, the application process for including new documentation, and expectations and guidelines for a party applying. 13 | 14 | This is aimed at larger projects. To suggest a new page or article please refer to the Suggesting content section in [What we write](/en_US/docs/MDN/Writing_guidelines/What_we_write#suggesting_content) 15 | 16 | ## Web standards technologies 17 | 18 | The remit of MDN Web Docs is to document web standards technologies that are in a specification published by a reliable standards body and are supported in at least one stable browser. These criteria signal enough interest, stability, and "intent to implement" by the web industry at large. Therefore, we think those technologies are a safe bet for us to spend our time and effort in documenting them. Any earlier than that, a web technology or a feature might be prone to getting cancelled due to lack of interest or might be so unstable that it might change significantly, which will needlessly involve lot of rewriting (which we try to avoid where possible). 19 | 20 | ## Non-web standards technologies 21 | 22 | Non-web standards technologies are technologies that do not follow our criteria summarized above. We would not normally consider them for documentation on MDN Web Docs. 23 | 24 | Our mission statement is _"to provide developers with the information they need to easily build projects on the open web"_. This suggests that we should consider documenting technologies that are useful to web developers, even if they are not open web standards, on the standards track, etc. 25 | 26 | If you want to consider a non-web standard technology for inclusion on MDN Web Docs, you should make sure that it matches the criteria below. 27 | 28 | ## Criteria for inclusion on MDN Web Docs 29 | 30 | Technologies should fulfill the criteria described here for being considered to be documented on MDN Web Docs. 31 | 32 | ### Be open and not proprietary 33 | 34 | At MDN Web Docs, we are supporters of open technologies. We don't support closed technology ecosystems that are controlled by a single entity, that are not open for contributions by any interested party, and that are not interoperable across multiple platforms and systems. We believe that technology works better for everyone when created out in the open. 35 | 36 | ### Be web-exposed and be related to web technologies 37 | 38 | Our central remit is web standards technologies; there is no point starting to document technologies that do not relate to the web or hold any interest to web developers. 39 | 40 | ### Show signs of interest and adoption 41 | 42 | We don't want to spend our time documenting a technology that has no signal of interest and adoption from the industry. It may just be that it is too early to start documenting the technology, and we could consider it to be documented on MDN Web Docs in the future. 43 | 44 | ### Not show signs of being deprecated or superseded 45 | 46 | Related to the above point, we also don't want to spend our time documenting a technology that is late in its lifecycle and is already showing signs of decline in interest. 47 | 48 | ### Not have an established documentation resource elsewhere 49 | 50 | There are many libraries and frameworks in existence, which are not web standards but are built on top of web technologies and are very popular in the web industry. We do not document any of these, because in general, they all have established documentation resources already. It would be foolish to compete with the official resource of a popular framework — to do so would be a waste of time and probably end up confusing developers trying to learn the technology. 51 | 52 | ### Have a community willing to write and maintain the documentation 53 | 54 | The MDN Web Docs team concentrates on documenting the open web platform. If you want a technology in this area to be considered for documentation on MDN Web Docs, you'll need to have a community assembled that is willing to write the documentation and maintain it after completion. Our team is happy to provide guidance in such cases, including edits and feedback, but we don't have the resource for more than that. 55 | 56 | > **Note:** MDN Web Docs work is carried out on GitHub and 'in the open'. Your team should be verse in git & GitHub and be comfortable with working in open source. 57 | 58 | ## Process for selecting the new technology 59 | 60 | If a technology looks like a good candidate for being documented on MDN Web Docs, you can [contact the team to propose and discuss the inclusion of this technology](). This section describes what the proposal should include. 61 | 62 | ### Submitting the proposal 63 | 64 | Technologies will be considered for inclusion on MDN Web Docs on a case-by-case basis. For consideration, you would need to submit a proposal titled "Proposal for documenting a new technology on MDN Web Docs". We would need the following information from you in the proposal: 65 | 66 | - The technology, its core purpose/use cases, and target developer audience. 67 | - What kind of industry or community buzz is there is around the technology? 68 | - Are a lot web developers using it? What is the industry adoption like? 69 | - Do a lot web developers want or need this information? 70 | - What is the size of the target audience for this information? Supporting statistics would help, if you have them. 71 | - How does the technology relate to core web technology and web browsers? Useful details include: 72 | - Does it use HTML and CSS but generally not output to the web? 73 | - Is it supported in web browsers via a polyfill? 74 | - What documentation or resources are already available that cover the technology? 75 | - How much documentation would need to be added to MDN Web Docs? 76 | - List the expected number of guides, tutorials, reference pages for elements/methods/attributes, etc. 77 | - Provide a high-level table of contents. 78 | - Mention the kind of "advanced" features you think you might need for this resource, beyond the basic documentation pages. Are you expecting to include embedded videos, interactive code samples, etc.? 79 | - Who will be writing the documentation? Who are they and why are they suited for the job? 80 | - How will the documentation be maintained 81 | 82 | You don't need to provide us with hundreds of pages of detail at this stage (in fact, we'd prefer it if you didn't). A couple of paragraphs on each of the above points is more than adequate. 83 | 84 | > **Note:** MDN Web Docs is primarily an English site (en-US). The primary language for your project should be in US English. 85 | 86 | ### Awaiting a response 87 | 88 | We will consider the technology and respond with one of the following answers: 89 | 90 | - **No**: We don't think this meets the criteria for being documented on MDN Web Docs. 91 | - **Maybe**: We are not sure if it is suitable for documenting on MDN Web Docs and would like to ask some further questions. 92 | - **Yes**: We think it is appropriate for including it on MDN Web Docs. 93 | 94 | If the technology is a good candidate, the team will assist you in getting started with the documentation. 95 | 96 | ## Project guidelines for documenting the new technology 97 | 98 | If your chosen technology is accepted for documentation on MDN Web Docs, the next step is to get started. 99 | 100 | To ensure that your project for documenting the new technology on MDN Web Docs is successful, we'll need you to have the following in place: 101 | 102 | - A dedicated team 103 | - A project plan and roadmap 104 | - Writing guidelines and standards 105 | - An intuitive documentation structure 106 | - A maintenance plan 107 | 108 | ### Dedicated team 109 | 110 | Make sure you have a dedicated team in place that will be there to both write the initial documentation as well as maintain it in future with the required updates. 111 | 112 | Have a think about how much work there is and how many people you might need for that. 113 | 114 | If it is a large project, you might benefit from having a few writers, a technical reviewer to check that the work is technically accurate, a copy editor to clean up the language, someone to write code examples, etc. 115 | 116 | On a smaller project, you might have one or two people taking on multiple roles. However you want to build up the team is fine as long as it works for you. 117 | 118 | A member of the MDN Web Docs team will be assigned to your project to provide guidance on the MDN Web Docs side of things. 119 | 120 | You should assign one (or two) team leads who can liaise with the MDN Web Docs team member. 121 | 122 | The MDN Web Docs representative will help get the required permissions to everyone on your team to work in the [MDN organization on Github](https://github.com/mdn). 123 | 124 | ### Project plan and roadmap 125 | 126 | Create a plan for the project — tasks, estimate completion dates, and milestones you would want to track to ensure you're making steady progress. 127 | 128 | If the project is large, you should consider assigning one of your team members as the project manager. You should also consider writing a sub-project plan for an initial release that encompasses the minimum set of documentation that is useful to publish (a _minimum viable product_); you can follow it up with further additions later. 129 | 130 | If the documentation project is small, you would still need to keep a record of what has been done and what hasn't, what stage each part of the documentation is at (e.g., not started, in progress, draft written, reviewed, done), and who is working on what. 131 | 132 | ### Writing guidelines and standards 133 | 134 | [These guidelines state](/en-US/docs/MDN/Writing_guidelines) how we expect documents to be written for MDN Web Docs. 135 | 136 | If you have additional guidelines for the documents you are writing, we expect this guide to be added to and kept up to date. 137 | 138 | In terms of standards, you are expected to maintain a reasonable level of writing quality for your documentation to stay on MDN Web Docs. Your MDN Web Docs representative will work with you to make you clear on what is expected. 139 | 140 | ### Intuitive documentation structure 141 | 142 | If you went through the proposal submission process then you should already have a rough outline of what you are going to write for this technology. At this point you should refine that into a site structure plan: think about what the document hierarchy will be and where everything will fit and link together. 143 | 144 | Each project is different, but we'd roughly recommend something like this: 145 | 146 | ``` 147 | Landing page 148 | | 149 | ------Reference 150 | | 151 | --------Elements 152 | | 153 | --------Methods 154 | | 155 | --------Other reference page type(s)? 156 | | 157 | ------Guides/tutorials 158 | | 159 | ------Examples 160 | ``` 161 | 162 | Each page type that you will use in your project should have a page template for others to copy the structure from. You should decide on these early on. 163 | 164 | Please refer to our section on page types, if additions need to be made please liaise with your MDN Web Docs representative. 165 | 166 | ### Maintenance plan 167 | 168 | The documentation for this technology will need to be maintained to remain on MDN Web Docs: 169 | 170 | - The content and files for MDN Web Docs are stored on Github. When others make changes to the documentation for your technology, a member from your team needs to review those changes to make sure the content is still good. You can track the open pull requests (PRs) via Github's notification feature. 171 | - When changes occur to the technology that require documentation to be updated, your team needs to make updates as appropriate, maintaining the same standards as the original documentation. 172 | 173 | If positive changes are not observed over a period of 6 months and the documentation appears to be: 174 | 175 | - Stale or unmaintained 176 | - Stalled without being finished 177 | - Low quality 178 | - Becoming obsolete 179 | 180 | Then the documentation for this technology will be considered dead. After a discussion between your team and the MDN Web Docs team representative, the documentation will be removed. 181 | 182 | We hope you understand that we need to be strict on such matters — we can't let the site fill up with bad quality, incomplete, or obsolete documentation. 183 | -------------------------------------------------------------------------------- /contrib-docs/writing-guidelines/writing-style-guide/code-style-guide/javascript/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Guidelines for styling JavaScript code examples 3 | slug: 4 | tags: 5 | - Code 6 | - Guide 7 | - Guidelines 8 | - JavaScript 9 | - MDN Meta 10 | --- 11 | {{MDNSidebar}} 12 | 13 | The following guidelines cover how to write JavaScript example code for MDN Web Docs. This is a simple list for writing concise examples that will be understandable by as many people as possible. For guidelines that go into more detail, we'd recommend the [AirBnB JavaScript Style Guide](https://github.com/airbnb/javascript), which is generally compatible with our guidelines. 14 | 15 | ## General guidelines for JavaScript code examples 16 | 17 | ### Syntax style 18 | 19 | - We use expanded syntax for JavaScript - each line of JavaScript on a new line, the opening brace of a block on the same line as its associated statement, and the closing brace on a new line. This maximizes readability and promotes consistency on MDN Web Docs. 20 | 21 | Follow this style for writing JavaScript code: 22 | 23 | ```js example-good 24 | function myFunc() { 25 | console.log('Hello!'); 26 | }; 27 | ``` 28 | 29 | Don't use this style for writing JavaScript code: 30 | 31 | ```js example-bad 32 | function myFunc() { console.log('Hello!'); }; 33 | ``` 34 | 35 | - All statements must end with semicolons (";"). Although they're technically optional in JavaScript, we require them in all our code examples because we feel that they convey where each statement ends and make the code clearer. 36 | - Use single quotes in JavaScript, wherever single quotes are needed in syntax. 37 | 38 | ### Spacing 39 | 40 | - There should be a space between a control statement and loop keywords and their opening parenthesis, as in `if () { ... }` and `for (...) { ... }`. 41 | - There should be a space between the opening parenthesis and the opening curly brace in such cases as described in the previous bullet. 42 | - Include spaces between operators and operands, parameters, etc. For example, this is more readable with the spaces: 43 | 44 | ```js example-good 45 | if (dayOfWeek === 7 && weather === 'sunny') { 46 | goOnTrip('beach', 'car', ['ice cream', 'bucket and spade', 'beach towel']); 47 | } 48 | ``` 49 | 50 | than this one without the spaces: 51 | 52 | ```js example-bad 53 | if (dayOfWeek===7&&weather==='sunny'){ 54 | goOnTrip('beach','car',['ice cream','bucket and spade','beach towel']); 55 | } 56 | ``` 57 | 58 | - Don't include padding spaces after and before opening and closing brackets. For example, use `(myVar)`, not `( myVar )`. 59 | 60 | ### JavaScript comments 61 | 62 | Use JS-style comments to comment code that isn't self-documenting. Also note that you should leave a space between the slashes and the comment. 63 | 64 | ```js example-good 65 | // This is a JavaScript-style comment 66 | ``` 67 | 68 | Put your comments on separate lines preceding the code they are referring to, like so: 69 | 70 | ```js example-good 71 | function myFunc() { 72 | // Output the string 'Hello' to the browser's JS console 73 | console.log('Hello'); 74 | // Create a new paragraph, fill it with content, and append it to the <body> 75 | let para = document.createElement('p'); 76 | para.textContent = 'My new paragraph'; 77 | document.body.appendChild(para); 78 | } 79 | ``` 80 | 81 | ### Modern JavaScript features 82 | 83 | In MDN Web Docs code examples, you can use the modern and well-supported JavaScript features, such as [arrow functions](/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions), [promises](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), [`async`](/en-US/docs/Web/JavaScript/Reference/Statements/async_function)/[`await`](/en-US/docs/Web/JavaScript/Reference/Operators/await), [`let`](/en-US/docs/Web/JavaScript/Reference/Statements/let)/[`const`](/en-US/docs/Web/JavaScript/Reference/Statements/const), [template literals](/en-US/docs/Web/JavaScript/Reference/Template_literals), and [spread syntax](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax). We have used them in many places in these guidelines. We believe that the web industry has gotten to the point where such features are familiar enough to be understandable. And for those that don't use them yet, we'd like to play our part in helping people to evolve their skills. 84 | 85 | ## Arrays 86 | 87 | ### Array creation 88 | 89 | For creating arrays, use literals and not constructors. 90 | 91 | Create arrays like this: 92 | 93 | ```js example-good 94 | let myArray = [ ]; 95 | ``` 96 | 97 | Don't do this while creating arrays: 98 | 99 | ```js example-bad 100 | let myArray = new Array(length); 101 | ``` 102 | 103 | ### Item addition 104 | 105 | When adding items to an array, use [`push()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) and not direct assignment. Given the following array: 106 | 107 | ```js 108 | const pets = []; 109 | ``` 110 | 111 | Add items to the array like this: 112 | 113 | ```js example-good 114 | pets.push('cat'); 115 | ``` 116 | 117 | Don't add items to the array like this: 118 | 119 | ```js example-bad 120 | pets[pets.length] = 'cat'; 121 | ``` 122 | 123 | ## Conditionals 124 | 125 | ### Loops 126 | 127 | When [loops](/en-US/docs/Learn/JavaScript/Building_blocks/Looping_code) are required, choose the appropriate one from [`for`](/en-US/docs/Web/JavaScript/Reference/Statements/for), [`for...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for...of), [`while`](/en-US/docs/Web/JavaScript/Reference/Statements/while), etc. 128 | 129 | - There should be _a space_ between a loop keyword and its opening parenthesis. 130 | - There should be _a space_ between the parentheses and the opening curly brace. 131 | - When using the `for` or `for...of` loop, make sure to define the initializer properly with a `let` keyword, as shown below: 132 | 133 | ```js example-good 134 | let cats = ['Athena', 'Luna']; 135 | for(let i of cats) { 136 | console.log(i); 137 | } 138 | ``` 139 | 140 | The example below does not follow the recommended guidelines for spacing or initialization. 141 | 142 | ```js example-bad 143 | let cats = ['Athena', 'Luna']; 144 | for (i of cats) { 145 | console.log(i); 146 | } 147 | ``` 148 | 149 | ### Switch statements 150 | 151 | Format switch statements like this: 152 | 153 | ```js example-good 154 | let expr = 'Papayas'; 155 | switch (expr) { 156 | case 'Oranges': 157 | console.log('Oranges are $0.59 a pound.'); 158 | break; 159 | case 'Papayas': 160 | console.log('Mangoes and papayas are $2.79 a pound.'); 161 | // expected output: "Mangoes and papayas are $2.79 a pound." 162 | break; 163 | default: 164 | console.log(`Sorry, we are out of ${expr}`); 165 | } 166 | ``` 167 | 168 | ## Control statements 169 | 170 | - There should be _a space_ between a control statement keyword and its opening parenthesis. 171 | - There should be _a space_ between the parentheses and the opening curly brace. 172 | 173 | Write control statements with proper spacing like this: 174 | 175 | ```js example-good 176 | if (iceCream) { 177 | alert('Woo hoo!'); 178 | } 179 | ``` 180 | 181 | The example below does not follow the spacing guidelines: 182 | 183 | ```js example-bad 184 | if (iceCream){ 185 | alert('Woo hoo!'); 186 | } 187 | ``` 188 | 189 | ## Error handling 190 | 191 | If certain states of your program throw uncaught errors, they will halt execution and potentially reduce the usefulness of the example. You should therefore catch errors using a [`try...catch`](/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) block, as shown below: 192 | 193 | ```js example-good 194 | try { 195 | console.log(results); 196 | } 197 | catch(e) { 198 | console.error(e); 199 | } 200 | ``` 201 | 202 | ## Functions 203 | 204 | ### Function names 205 | 206 | For function names, use lowerCamelCasing. Use concise, human-readable, and semantic names where appropriate. 207 | 208 | The following is a good example for a function name: 209 | 210 | ```js example-good 211 | function sayHello() { 212 | alert('Hello!'); 213 | }; 214 | ``` 215 | 216 | Don't use function names like these: 217 | 218 | ```js example-bad 219 | function SayHello() { 220 | alert('Hello!'); 221 | }; 222 | 223 | function notVeryObviousName() { 224 | alert('Hello!'); 225 | }; 226 | ``` 227 | 228 | ### Function declarations 229 | 230 | - There should be _no space_ between a function name and its opening parenthesis. 231 | - There should be _a space_ between the parentheses and the opening curly brace. 232 | - Where possible, use the `function` declaration to define functions over function expressions: 233 | 234 | This is the recommended way to declare a function: 235 | 236 | ```js example-good 237 | function sum(a, b) { 238 | return a + b; 239 | } 240 | ``` 241 | 242 | This is not a good way to define a function: 243 | 244 | ```js example-bad 245 | let sum = function(a, b) { 246 | return a + b; 247 | } 248 | ``` 249 | 250 | - When using anonymous functions inside a method that requires a function as a parameter, it is acceptable (although not required) to use an arrow function to make the code shorter and cleaner. 251 | 252 | This is the recommended way: 253 | 254 | ```js example-good 255 | const array1 = [1, 2, 3, 4]; 256 | let sum = array1.reduce((a, b) => 257 | a + b 258 | ); 259 | ``` 260 | 261 | Instead of this: 262 | 263 | ```js example-good 264 | const array1 = [1, 2, 3, 4]; 265 | let sum = array1.reduce(function(a, b) { 266 | return a + b; 267 | }); 268 | ``` 269 | 270 | ## Objects 271 | 272 | ### Object names 273 | 274 | When defining an object class, use UpperCamelCasing (also known as PascalCasing) for the class name and lowerCamelCasing for the object property and method names. 275 | 276 | When defining an object instance, either a literal or via a constructor, use lowerCamelCase for the instance name, like so: 277 | 278 | ```js example-good 279 | let hanSolo = new Person('Han Solo', 25, 'male'); 280 | 281 | let hanSolo = { 282 | name: 'Han Solo', 283 | age: 25, 284 | gender: 'male' 285 | } 286 | ``` 287 | 288 | ### Object creation 289 | 290 | For creating general objects (i.e., when classes are not involved), use literals and not constructors. 291 | 292 | For example, do this: 293 | 294 | ```js example-good 295 | let myObject = { }; 296 | ``` 297 | 298 | Don't create a general object like this: 299 | 300 | ```js example-bad 301 | let myObject = new Object(); 302 | ``` 303 | 304 | ### Object classes 305 | 306 | Use ES class syntax for objects, not old-style constructors. 307 | 308 | For example, this is the recommended way: 309 | 310 | ```js example-good 311 | class Person { 312 | constructor(name, age, gender) { 313 | this.name = name; 314 | this.age = age; 315 | this.gender = gender; 316 | } 317 | 318 | greeting() { 319 | console.log(`Hi! I'm ${this.name}`); 320 | }; 321 | } 322 | ``` 323 | 324 | Use `extends` for inheritance: 325 | 326 | ```js example-good 327 | class Teacher extends Person { 328 | ... 329 | } 330 | ``` 331 | 332 | ## Operators 333 | 334 | ### Conditional operators 335 | 336 | [Conditional (or ternary) operators](/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_Operator) should be put on a single line, as shown below: 337 | 338 | ```js example-good 339 | let status = (age >= 18) ? 'adult' : 'minor'; 340 | ``` 341 | 342 | Don't nest the conditional operators, as shown below, because the code is harder to read: 343 | 344 | ```js example-bad 345 | let status = (age >= 18) 346 | ? 'adult' 347 | : 'minor'; 348 | ``` 349 | 350 | ### Strict equality operator 351 | 352 | Always use the ["strict" equality](/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality) and inequality operators over the equality and inequality operators. 353 | 354 | Use the strict equality and inequality operators like this: 355 | 356 | ```js example-good 357 | name === 'Chris'; 358 | age !== 25; 359 | ``` 360 | 361 | Don't use equality and inequality operators, as shown below: 362 | 363 | ```js example-bad 364 | name == 'Chris'; 365 | age != 25; 366 | ``` 367 | 368 | ### Shortcuts for boolean tests 369 | 370 | Use shortcuts for boolean tests. For example, use `x` and `!x`, not `x === true` and `x === false`. 371 | 372 | ## Strings 373 | 374 | ### Template literals 375 | 376 | For inserting values into strings, use [template literals](/en-us/docs/Web/JavaScript/Reference/Template_literals). 377 | 378 | This is an example of the recommended way to use template literals: 379 | 380 | ```js example-good 381 | let myName = 'Chris'; 382 | console.log(`Hi! I'm ${myName}!`); 383 | ``` 384 | 385 | Don;t concatenate strings like shown below: 386 | 387 | ```js example-bad 388 | let myName = 'Chris'; 389 | console.log('Hi! I\'m' + myName + '!'); 390 | ``` 391 | 392 | ### Text content of a node 393 | 394 | When inserting strings into DOM nodes, use {{DOMxRef("Node.textContent")}} and not {{DOMxRef("Element.innerHTML")}}. `textContent` is a lot more efficient and less error-prone than `innerHTML`. 395 | 396 | The example below shows the use of `textContent`. 397 | 398 | ```js example-good 399 | let text = 'Hello to all you good people'; 400 | const para = document.createElement('p'); 401 | para.textContent = text; 402 | ``` 403 | 404 | Don't use `innerHTML` to insert strings into DOM nodes. 405 | 406 | ```js example-bad 407 | let text = 'Hello to all you good people'; 408 | const para = document.createElement('p'); 409 | para.innerHTML = text; 410 | ``` 411 | 412 | ## Variables 413 | 414 | ### Variable names 415 | 416 | For variable names, use lowerCamelCasing. Use concise, human-readable, and semantic names where appropriate. 417 | 418 | Use variable names like shown here: 419 | 420 | ```js example-good 421 | let playerScore = 0; 422 | 423 | let speed = distance / time; 424 | ``` 425 | 426 | Don't name variables like this: 427 | 428 | ```js example-bad 429 | let thisIsaveryLONGVariableThatRecordsPlayerscore345654 = 0; 430 | 431 | let s = d/t; 432 | ``` 433 | 434 | > **Note:** The only place where it's OK to not use human-readable, semantic names is where a very commonly recognized convention exists, such as using `i` and `j` for loop iterators. 435 | 436 | ### Variable declarations 437 | 438 | When declaring variables and constants, use the [`let`](/en-US/docs/Web/JavaScript/Reference/Statements/let) and [`const`](/en-US/docs/Web/JavaScript/Reference/Statements/const) keywords, not [`var`](/en-US/docs/Web/JavaScript/Reference/Statements/var). The following examples show what's recommended and what's not on MDN Web Docs: 439 | 440 | - If a variable will not be reassigned, prefer `const`, like so: 441 | 442 | ```js example-good 443 | const myName = 'Chris'; 444 | console.log(myName); 445 | ``` 446 | 447 | - If a variable will be reassigned, use `let` as shown below: 448 | 449 | ```js example-good 450 | let myAge = '40'; 451 | myAge++; 452 | console.log('Happy birthday!'); 453 | ``` 454 | 455 | - The example below uses `let` where it should prefer `const`. The code will work but this usage should be avoided in MDN Web Docs code examples.- 456 | 457 | ```js example-bad 458 | let myName = 'Chris'; 459 | console.log(myName); 460 | ``` 461 | 462 | - The example below uses `const` for a variable that gets reassigned. The reassignment will throw an error. 463 | 464 | ```js example-bad 465 | const myAge = '40'; 466 | myAge++; 467 | console.log('Happy birthday!'); 468 | ``` 469 | 470 | - The example below uses `var`, which should be avoided in code examples on MDN Web Docs. 471 | 472 | ```js example-bad 473 | var myAge = '40'; 474 | var myName = 'Chris'; 475 | ``` 476 | 477 | ## See also 478 | 479 | - [JavaScript language reference](/en-US/docs/Web/JavaScript/Reference) - browse through our JavaScript reference pages to check out some good, concise, meaningful CSS snippets. Our interactive examples in the "Try it" section are generally written to follow the guidelines described on this page. 480 | - For API examples, you can check out the following: 481 | - [`fetch()` examples](/en-US/docs/Web/API/fetch#examples) 482 | - [`fillRect()` examples](/en-US/docs/Web/API/CanvasRenderingContext2D/fillRect#examples) 483 | - [Payment Request API `show()`](/en-US/docs/Web/API/PaymentRequest/show) 484 | - [Using the Web Audio API](/en-US/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) - this covers general good practices for HTML, CSS, and JavaScript and also provides a good demonstration of how to use snippets and add links to full examples elsewhere. 485 | - [Using the Media Capabilities API](/en-US/docs/Web/API/Media_Capabilities_API/Using_the_Media_Capabilities_API) 486 | --------------------------------------------------------------------------------