MDN Canvas documentation updated

[Florian Scholz]

Hi,

the following is a project review of the work that I did on the MDN
canvas documentation (this work is one Q1 deliverable for me).
You can also read this on the project umbrella bug:
https://bugzilla.mozilla.org/show_bug.cgi?id=1054983#c6

90 new pages have been added (from 22 to 112) and ca. 30 dev-doc-needed
and documentation request bugs have been resolved.

Documentation created and updated as part of this project:

Landing page:
https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API

Tutorial (13 pages/chapters):
https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial

Reference pages:
https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement (9 pages)
https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D (67
pages)
https://developer.mozilla.org/en-US/docs/Web/API/CanvasGradient (2 pages)
https://developer.mozilla.org/en-US/docs/Web/API/CanvasPattern (2 pages)
https://developer.mozilla.org/en-US/docs/Web/API/ImageData (5 pages)
https://developer.mozilla.org/en-US/docs/Web/API/TextMetrics (2 pages)
https://developer.mozilla.org/en-US/docs/tag/Path2D (3 pages)

Some related example articles and demos have been polished, too. A
"{{canvasSidebar}}" navigation has been added to quickly browse this
documentation set.

The motivation for this project was that the canvas material on MDN has
been a complete mess. Especially the reference part was not existent and
sometimes wrong. Pages mentioned old APIs, which were already removed
from Gecko. Canvas as a whole was not really explorable with just 22
pages. The single reference page had not a single code sample. The
tutorial was the only way to see how bits of canvas work.

I carefully rewrote the main CanvasRenderingContext2D reference and
added sub pages for each method/property. The non-standard APIs are
still mentioned, but in their own section
(https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D#Non-standard_APIs).
Their usage has been clearly marked as deprecated/obsolete and a
standards-based solution is offered.

I introduced "playable live samples"
(https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D.fillRect#JavaScript).
I hope that it makes the canvas code more explorable now that you can
fiddle with some code and get the visual feedback directly.

The whole documentation is browser neutral, like all our open web
documentation is. Canvas has been documented in the light of the
standards-document and thus features which are not yet in Gecko have
been documented, too. I noted also when they are present in other
engines and are useful for web developers. Browser compatibility tables
and indicators for new/experimental features have been added, so that
the reader is aware of this.

To help our product, Gecko, I took the opportunity to triage and file
bugs against our implementation (bug 1119470) and also fixed easy bugs
there (bug 1119527). I think this is a good model how I, as a Technical
Writer for open web docs, can give back more to the web platform and
Gecko. I like being this sort of "open web engineer". This is not very
difficult for me, because for the documentation I have to read the
specifications and implementation status of different engines very
careful anyway. It consumes some extra time, but I think it has a good
impact for Gecko and for web developers who want to use the feature
cross-platform and without bugs in the end.

I very much welcome feedback and review of the canvas docs on MDN.

Thank you,
Florian

--
Florian Scholz
Technical Writer
Mozilla Developer Network

[Chris Mills]

Wow, just wow. This is fantastic work, congrats!

One little nitpick I thought I’d mention - where you include the PrevNext links at the bottom of each tutorial article, I’d suggest including them at the top as well - often readers like to flick through/browser a tutorial series rapidly, to get to where they left off, or just see what the overall state is like.

Another thought - a persistent link to the TOC/main article listing would also be nice. Do we have any kind of macro for that?

I’ll let you know if I notice anything else.

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

> _______________________________________________
> engagement-developers mailing list
> engagement...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/engagement-developers