How to document a CSS property

Little by little new properties are added to CSS. The MDN CSS Reference needs to be kept up-to-date with these developments. This document describes how to add a CSS property reference page by guiding you step by step.

Each CSS property reference page follows the same structure: it allows the reader to find the relevant information quickly once familiar with how and where the information is displayed. With that, the amount of search to find a specific information in the references, is reduced enormously for the everyday reader.

Step 1 — Decide which property to document

First, you need to decide which property to document. For example, the CSS Documentation status page list properties that need to be documented. To know more details about the new CSS property you need to find a relevant specification for it (e.g. a W3C specification, a wikimo page with further details or a bug report containing information for a non-standard property an rendering engine like Gecko or Blink implements).

Step 2 — Check the database of CSS properties

Several characteristics of a CSS property, like 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.

If not, contact an admin or a power user, either on IRC #mdn channel, or, if nobody is available, by filing a bug.

Step 3 — Creating the CSS property page

Preperations 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. We will go through the different steps now.

1. Clone the following page, set the title to your-property (without capitals) and the slug to Web/CSS/your-property.
2. Change the summary to fit, but keep it starting the same way : "The your-property CSS property…". Explain briefly what this property is for.
3. If the property is not experimental, remove the {{SeeCompatTable}} macro. A property is not experimental if it is on the standard track (that is, in an official spec), its spec is a Candidate Recommendation, a Proposed Recommendation, or a Recommendation, and it is not listed as a feature at risk in it. If the property is not on the standard track, replace the macro by the {{Not_standard}} macro.
4. Replace the parameter of the {{cssinfo("animation-name")}} macro by the name of the CSS property you are documenting. This will allow you to build the summary box using the data you entered in step 2.
5. Replace the example of the syntax by relevant ones. Keep them very simple and don't forget that a lot of people don't understand a formal syntax so it needs to be simple and exhaustive. Keep the inherit, initial, and unset keywords examples at the end. It reminds users that these are valid values, too.
6. Under the chapter Values, put the meaning of each value. If it is a keyword, don't forget to mark it as code (select it and press CTRL-O). Each description should start by "Is a" followed by the type of the value, or indicating it is a keyword.
7. Clear the Examples chapter, we will add them at the end!
8. Update the specification table. For information about how to do it, read this tutorial.
9. Update the compatibility information. For information about how to do it, read this tutorial.
10. Update the See also section with relevant links. Do not link to specs here and usually link to internal documents. External documents are welcome, but only if they bring really good information. There are spam or SEO links often, so don't worry if external links are removed sometimes. Just start the discussion if you still find it useful and want to see it back.
11. Add the relevant tags: you need to add CSS, CSS Property, and Reference. You also need to add Experimental or Non-standard if this is the case. Finally you also need to add a CSS XYZ tag, where XYZ stands for the group of CSS properties it belongs to. It is often the spec short name. All these tags are used to generate quicklinks and other niceties.

At any point, you can save by hitting the SAVE button. You can continue to edit right along. If you haven't saved your page until now, please do so! :-)

The last step is to add Examples. To do that follow this tutorial about 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, examples for list-style-type will show what the different values generate, but not how to combine it with other property, pseudo-classes or pseudo-elements to generate nice effects; tutorials and guide can be written to show more.

Step 4 — Getting a review

You have documented your CSS property! Congratulations!

In order to have a good quality and consistency throughout the MDN CSS reference, it is good practice to request a review. Just click on the checkbox at the bottom of the article (in edit mode), and, optional, if you want to have a more personal review helping you to improve editorial skills, ask for it on the dev-mdc mailing list.

Step 5 — Integrating the new page in the MDN

Now that your page is created, you want it to be found by the readers. Adding tags helped about this already as it allowed it to appear in the quicklinks to related CSS pages. Also you want it to appear on the CSS index page. If the newly documented property is on the standard track and at least one major browser is implementing it, it deserves to be listed this. Only administrator can add it there, so contact the CSS driver on IRC (currently at #mdn ping teoli) or file a documentation bug requesting it.

Also, if the property is implemented by Firefox, you need to check that it is listed, and linked! in the correct Firefox for developers MDN page. The new CSS property is likely already listed in the HTML section, just be sure that its name links back to your newly created page.