Update and complete the canvas documentation

RESOLVED FIXED

Status

Developer Documentation
API: Miscellaneous
P2
normal
RESOLVED FIXED
3 years ago
3 years ago

People

(Reporter: sheppy, Assigned: fscholz)

Tracking

Details

(Whiteboard: [DocArea=Canvas])

(Reporter)

Description

3 years ago
:: Developer Documentation Request

      Request Type: New Documentation
     Gecko Version: unspecified
 Technical Contact: gwright@mozilla.com

:: Details

The canvas documentation as it stands is a mess. The reference for the element itself is okay but there's little documentation for the context rendering API; that needs writing.

In addition, the guide material was first written before the API was standardized and has been updated haphazardly since. We need to gather that all up, clean it up, and update it all to be accurate and up-to-date.

The doc plan page for this project is here: https://developer.mozilla.org/en-US/docs/MDN/Plans/Canvas
(Reporter)

Updated

3 years ago
(Assignee)

Comment 1

3 years ago
Moved existing content to the new home of canvas docs:
https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API

Doc status page: https://developer.mozilla.org/en-US/docs/MDN/Doc_status/API/Canvas
At this point we have 22 reference and guide pages and 15 dev-doc-needed bugs. Some of the reference pages are completely unusable.

I am looking into this and will ask the writing team, if I can take over this work in q4 and/or q1.
(Reporter)

Comment 2

3 years ago
Finding someone to do this work is fairly important, and I think Q4 or Q1 is reasonable. I will say that it's likely to be interesting work, by and large.
(Assignee)

Comment 3

3 years ago
Taking.
Assignee: jypenator → eshepherd
Component: API: HTML → API: Miscellaneous
Priority: P5 → P2
Whiteboard: [DocArea=Canvas]
(Assignee)

Updated

3 years ago
Assignee: eshepherd → fscholz
OS: Other → All
(Assignee)

Updated

3 years ago
Depends on: 878149
(Assignee)

Comment 4

3 years ago
Just for the record, stats before starting any work here:

Total pages: 22
Needs* tags: 5
Editorial reviews: 1
Technical reviews: 1
Outdated pages: 1
Dev-doc-needed requests: 15 
Documentation bug requests: 10
(Assignee)

Comment 5

3 years ago
First milestone:

* <canvas> element page updated:
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas

* HTMLCanvasElement interface page updated (plus 8 subpages for methods/properties):
https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement

Partly reviewed by :teoli already.
(Assignee)

Updated

3 years ago
Depends on: 1078186
(Assignee)

Updated

3 years ago
Depends on: 1080128
Depends on: 886069
(Assignee)

Updated

3 years ago
Depends on: 1095437
(Assignee)

Updated

3 years ago
No longer depends on: 886069
(Assignee)

Updated

3 years ago
No longer depends on: 1095437
(Assignee)

Comment 6

3 years ago
Project review:

Stats before and after:

Total pages: 22 -> 112
Needs* tags: 5 -> 0
Editorial reviews: 1 -> 0
Technical reviews: 1 -> 0
Outdated pages: 1 -> 0
Dev-doc-needed requests: 15 -> 0 (plus some that had no ddn keyword)
Documentation bug requests: 10 -> 0

90 new pages have been written and ~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.

As said in comment 0, the canvas material on MDN was 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 reference had not a single code sample. The tutorial was the only way to see how bits of canvas work.

The main reference CanvasRenderingContext2D has been carefully rewritten and now has 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.

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 when they are present in other engines and 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 am going to send a similar summary to the MDN mailing list and will ask for further feedback and review there.
For now, I am going to call this bug fixed.
Status: NEW → RESOLVED
Last Resolved: 3 years ago
Resolution: --- → FIXED
You need to log in before you can comment on or make changes to this bug.