Re: SVG Docs strategy

Sorry for the delay, but I meant to add my 2 cents.  I wrote a half
dozen of those SVG tutorials a year ago, the ones titled "smarter"
until I realized SVG hadn't become nearly as easy to integrate with
HTML as I thought. ;-)  Sorry they don't fit so well into the
beginner/advanced mold. And I got pulled from the project
unexpectedly, so a few of them are not as useful as I had hoped.

FYI, I filed a bug relevant to SVG ref doc re-org that you should know about:
http://project.webplatform.org/content/issues/37
All the imported "attribute" pages were mislabeled as "properties" &
vice versa.  (Where what should be called "properties" are implemented
as CSS even if they can also be specified using attribute syntax.)

I ran some globals way back to do some superficial cleanup after I had
noticed that a good deal of embedded content was not actually
rendering due to some template issue.  As I recall, much of it was due
to tables getting dropped, and I fixed it by getting rid of the column
headers & converting them to DT/DD-style listings.  I only mention
this because the doc appeared to be a real mess, and there may be
other latent formatting problems that are preventing content from
rendering.  AFAIK, the templating system has no way to detect such
problems.

Good luck. Wish I could help,

--Mike Sierra




On Tue, Apr 29, 2014 at 2:51 PM, Amelia Bellamy-Royds
<amelia.bellamy.royds@gmail.com> wrote:
> 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

Received on Wednesday, 7 May 2014 15:37:36 UTC