Helping with the SVG Documentation

MDN
#1

Hi Everybody,

For those who wish to contribute with the SVG documentation revamp/clean up I provide here a set of instruction to help you find your way through in order to contribute efficiently and satisfyingly :slight_smile:

First of all, the on-going progress of that project is tracked in that spreadsheet. It will give you a full overview of the current state of things. If you do contribute, please update the spreadsheet accordingly.

Note: Even if there are goals for end of June, this is not a contest and it’s okay to miss the goal as long as the work has been done in a qualitative way (in other words always value quality over quantity).

Okay, that said, what can you do to help?

  1. Contribute and review BCD information
    Browser Compatibility Data are one of the key goals for MDN this year, and SVG is no exception to that. Such data are contributed on GitHub and we have plenty of PRs that await to be either created (especially for SVG DOM APIs) or reviewed.

  2. Revamp existing articles
    The reference documentation of SVG elements, attributes and DOM APIs needs to be seriously cleaned up. That clean up include the following actions:

    • Clean up the page structure
    • Add/move a basic example on top
    • Update the content to match the last addition from the new SVG2 specification and the current state of implementation.
    • Update the attribute list to provide a basic documentation of all the specific attributes and some links to the relevant SVG global attributes.

    Unsure about how to deal with all those changes? No problem, take a look at the pages marked as “Updated” and if it’s steel unclear, ask in that discourse thread :wink: What is important here is consistency.

  3. Create missing article
    All the stuff marked as TBD needs to be created!

  4. Clean up and add examples
    Examples are very important to better understand SVG. They need to be short, clean and to the point. The work on examples covers several aspects:

    • Make examples on top interactive (before doing that, we need to wait for the HTML interactive example tool to be ready)
    • Clean up examples for unnecessary code (update or remove depending on their relevance)
    • Remove outdated examples
    • Create missing examples
    • For all non-interactive examples, make sure they are all embeded with their code in the page using the {{EmbedLiveSample}} macro

    Here are a few requirements for SVG examples:

    • Always add an SVG root element.
    • The SVG root element should always have the viewBox and xmlns attributes. Other attributes on the SVG root element are forbidden unless they are absolutely necessary for the example. For example you should never add the width and height attributes (except for the very few examples that demonstrate their very impact) but you should add the xmlns:xlink attribute for all examples requiring XLink attributes somewhere in the example.
    • Avoid unnecessary styling (and avoid presentation attributes as much as possible). If you need some style set up for the sake of clarity, use an hidden style block. See the following point, which is a perfect example of that:
    • Always add a hidden style block containing the rule: html,body,svg { height: 100%; } This is necessary to be sure the examples will be displayed in the example iframe without any scroll bars.

I hope this will help you to get onboard :slight_smile: Feel free to ask me any questions if you need to know more or if you want to be mentored.

2 Likes