Time to lift up the SVG documentation to the next level

MDN
#1

Hi everybody,

Among my various goals for Q1 & Q2, I commit myself to work back on the SVG Documentation. 8 years later that documentation has become a bit old and would benefit from more attention.

Before I jump in blindly I wish to discuss a bit with you all to get your opinion and to share some though on this.

My current plan is the following:

  • Moving all SVG BCD information on GitHub (It will be my Hack On MDN project for March)
  • Rework the SVG reference pages to match the same structure as HTML (mostly, removing/redirecting the attribute pages to put their information directly within the element pages and only keeping generic attributes like it has been done for HTML)
  • Add at least on example on top of every element pages (possibly interactive)
  • Fully rework the SVG Tutorial, which is severely outdated. (It would also very likely benefit to be moved under the Learn section)

I intent to work on the three first point in Q1/Q2. For the SVG tutorial, it’s a huge job and I’m wondering if it couldn’t benefit from using a contractor to help us on that.

At that stage I only did a quick inventory, and I would love to hear your opinion/expectation on all of this.

Best,
Jeremie

3 Likes
#2

I’m glad to see the SVG docs getting some love. I suspect that most web developers won’t be creating SVG files by hand. More likely, they would be tweaking a file created by a tool such as Inkscape. (We could validate this with surveys or other research.) So, they will be very “action-oriented” — they want to fix one thing, not learn everything about SVG.

#3

I agree, Janet, that’s most likely how the docs will be used by most people. It may even be useful to have an article on finding the place in the SVG that corresponds to what you want to change, given that they didn’t write the SVG themselves. Some tips on that could be useful, especially for people who infrequently navigate XML-style markup.

#4

I also agree with this; my experiences are similar. I use SVG in a very superficial way — make a shape with inkscape, stick it in the page, then add some classes to a few of the elements so I can mess with them using CSS and/or JavaScript.

However I also think that the reason a lot of people don’t use SVG for anything cleverer is that they simply don’t know what SVG is capable of. I think this could be a really good chance not only to update our coverage to make it modern, but also to do some SVG evangelism — hey, did you know you can do these awesome things, or do this kind of thing more easily using this feature?

#5

Chris: That’s an excellent point. Perhaps there’s a way to make a determination as to how much more likely people would be to use SVG to do things if they knew what it could do and how to do it. Maybe we could do a short “intro to SVG” article that demonstrates some of the concepts, maybe gives them something more complicated with some ideas for ways to fiddle with it in an interactive way, then try to compare people’s thoughts on SVG before and after going through that?

#6

Yup, I think some kid of SVG interactive examples would be great for the updated SVG tutorial series. I think it is worth updating these docs, regardless of people’s thoughts, but we could certainly shape the tutorials further and improve their effectiveness if we had such data.

#7

Hi!

I agree that fully creating SVG by hand is a very limited use case (even for people like myself who are very familiar with the technology). It is extremely impracticable to create a complex shape by hand and using a vector drawing tool (Inskape, Illustrator, Sketch, …) or a scripting library (D3.js, Snap.svg, Bonsai.js, Chartist, …) is a necessary step.

However, I also agree with Chris that there is a lot of power with SVG when you know how to get the best of it, see:

And there are many more fun stuff to create :slight_smile:

So I think it will be interesting to shape a large part of the SVG tutorial around “how to improve your SVG content” rather than just “how to create SVG content”.

#8

Thanks Jeremie for working on this, it’s great to see an update to this part of MDN. It might also be useful to look at traffic data to determine interest: The 20 or so tutorial pages receive 25% of the overall traffic to SVG pages, and ~13 reference pages receive another 25%. Assuming 500 or so reference pages total, that’s quite a lot. Might be worth taking that into consideration for prioritization.