SVG Docs strategy

Hello all,

Doug Schepers has been hinting that he'd love to have the SVG section be
the focus of concerted clean-up efforts via Doc Sprints or Webplatform
Wednesday initiatives.  At the end of last week's tele-conference I
promised to write up an overview of what I thought were the main things
that needed to be done.  On today's telcon (29 April 2014), there was
support for making this the next content push, and creating an informal
task group to create a focused strategy, collaborating via email and one or
two dedicated teleconferece calls.

So...
If you are interested in making webplatform.org the go-to SVG reference on
the web, get in touch!  Even if you don't have any SVG experience, there
will be lots of editorial clean-up work you can help out with.  But we'd
also like to get some expert SVG designers involved -- if you know of any
who might be interested, now's a good time to to convince them they should
be contributing to WebPlatform Docs.

Here's where we're at:

The SVG reference pages currently consist (almost exclusively) of
unreviewed imports from MSDN.  There are two main problems with that:

* The MSDN docs (unlike the established webplatform pages) are organized
around DOM objects and properties, and don't have separate pages for
elements versus interfaces, attributes versus DOM properties.

* A summary of each method and property is duplicated in every page that
references it, instead of being dynamically generated from Semantic
Mediawiki connections.

If you worked on cleaning up the other sections of MSDN doc imports, you'll
be familiar with those issues.  However, there are added complications with
SVG:

* Not only do the specs define an interface (API/DOM object) for nearly
every element type, but there are many abstract interfaces that define
common features (properties or methods) that should be implemented by
specific elements; there don't currently appear to be any pages in the docs
for these interfaces, but we'll need them to auto-generate lists of
inherited features.

* There are also other DOM objects unique to SVG which *don't* correspond
to SVG elements (they mostly represent data types or attribute values, e.g.
transformation matrices or path segment types).

* There are two distinct types of SVG attributes: normal XML attributes
(which currently are represented in the docs only by their associated DOM
property pages), and presentational attributes (currently the total content
of the "SVG attributes" category).  XML attributes apply to specific types
of elements and only apply to the element on which they're declared.
 Presentational attributes are essentially SVG-specific CSS styles; they
can be specified in attribute form or CSS form but either way they are part
of the cascade and so can be over-written by more specific rules, or
declared on any element and inherited by its children.

* There are non-browser software (Illustrator, Inkscape) that use SVG and
maybe should be considered for compatibility purposes.  (But that doesn't
have to be done now, it could be part of a future project to create
additional compatibility tables beyond the current Desktop browser/mobile
browser tables, e.g. a table for compatibility with accessibility
technologies.)

With all that in mind, my initial proposal for the top-level organization
of the SVG docs would be something like:
_______________________________
(http://docs.webplatform.org/wiki/svg)
=SVG=
==Summary==

==Learning Material==
* Beginner's Guide
* Advanced Techniques

==Reference Pages==
* SVG Elements
* Element Attributes
* Presentational Attributes
* SVG DOM Objects
* SVG DOM Properties
* SVG DOM Methods
* SVG Data Types

==Background==
==Index==
_______________________________

The SVG DOM Objects category would include all interfaces, abstract and
concrete, as well as other SVG-specific DOM objects; for element interfaces
the content could just be a link to the main element page and lists of
inherited properties/methods.

Likewise, where SVG DOM properties are just the accessible API name of an
attribute, the page content would just be a link (or maybe a redirect) to
the corresponding attribute page.

SVG Data Types would include a lot of cross-links to HTML, Javascript and
CSS data type pages, but there are unique features like being able to use
scientific notation for numbers and the concept of "user units".

It's a completely separate issue, but I think there is a benefit to
splitting up the SVG learning material into beginner and advanced sections;
currently it's just an unorganized list of imported tutorial pages.  It
sounded like there was strong support for a more structured tutorial
organization from participants of today's Telcon.

The first step is therefore deciding on whether that's what people want the
SVG docs to look like.  Some things to consider:

* Is my proposed reference page categorization too complicated?  If so,
which categories should be combined?

* Should essentially duplicate DOM vs XML pages just be redirects, or
should we maintain separate but linked pages?

* Which version (element/attribute vs object/property) should have the
major content and which the link/redirect?

* Should we split element interface DOM pages from  SVG Objects -- and
should any of these be in the main DOM docs instead of in the SVG docs?

Once the main structure is decided (hopefully in the next few weeks), the
implementation tasks can be divided into major MediaWiki organizational
changes, clean-up/review work, and content-focused work.  A rough outline
of what I think will be required:

Major Organizational Tasks
====================
These need to be done before the clean-up can occur.  I'm willing to
volunteer to do some or all, although more help would mean getting it done
sooner.

* Create all the categories & templates for the above structure (or
whatever is finally decided on)

* Create Semantic Mediawiki properties for the templates, particularly for
auto-completing templates based on inheritance

* Create top-level descriptive pages and summaries for each category

Clean-up Tasks
===========
These would be suitable for crowd-sourcing efforts like Doc
Sprint/Webplatform Wednesdays.  A lot of cut-and-paste work to move blocks
of text from the imported docs into the correct pages, and a lot of
cross-referencing the specs to correctly define which objects implement
which interfaces, and which interfaces define which methods/properties.
 Once the forms and templates are finalized it will be possible to more
explicitly define how to do each of these tasks.

* Split XML versus DOM reference pages: create DOM object pages by
splitting the element pages and create element attribute pages by splitting
the object property pages, with summaries and links/redirects (whichever is
decided)

* Go through the SVG specs and create stub pages for every object/interface
type if they don't yet exist, with links to the correct method/property
pages

* Review all the DOM object pages and set the inheritance properties

* Once inheritance has been set, review the page and make sure all the
methods & properties mentioned in the (raw imported) text are included
in either the auto-generated lists of inherited members or the list of
members for this interface; if so, delete the duplicate text, if not,
figure out which interface should have that property/method and add the
link.  Cross-check with the specs to identify any properties/methods not
included in the MSDN docs.

Tasks for SVG Experts
=================
These require SVG expertise but not (much) Mediawiki expertise.

* Go through the tutorials and identify which ones are beginners versus
advanced; also make sure all the tutorials have good summaries and are
browser-neutral.

* Identify missing tutorial subjects and write them; in doing so, consider
frequently asked questions on sites like StackOverflow

* Flesh out the stub concept pages for each of the reference categories
 (e.g., describing the difference between element attributes and
presentational attributes)

* Create better/more beautiful examples, preferably using the
code.webplatform.org live example site. (Maybe the goal for ref pages
should be to have one super-simple example to just show the concept, and
one or more elegant design examples of the concept applied to a
real-world design problem?)


I hope that's enough to get the ball rolling without scaring anyone away.
 Looking forward to hearing ideas and suggestions (and offers to
volunteer!).

--Amelia Bellamy-Royds