Re: JS page templates and topics (analysis)

On 12/7/2013 9:57 PM, Eliezer Bernart wrote:
> Once we start with a non-multi-layered approach and we want to change 
> to a multi-layered, how difficult or painful it will be the process to 
> do this update?

That question brings us to the second part.  Topic clusters.

To adhere to the principles described at http://is.gd/kl5LIu , where it 
says, "We use topic clusters to group articles of similar topics ... 
Topic clusters produce a list of related topics in the See Also 
section," we would split the one new topic "JavaScript language" into 
multiple topic clusters.  A top-level page for that cluster could have 
automatic listing of the relevant pages.

A first jaunt down that line of reasoning would, perhaps, lead us to 
choose topic clusters obtained from the top-level links on the 
javascript reference page:

     http://docs.webplatform.org/test/javascript/javascript_reference

Where we read these potential topic clusters within the single 
"JavaScript language" topic pages:

     Objects   (about 24 pages in javascript/*)
     Constants  (about 20 pages in javascript/*/constant or 
javascript/constant)
     Properties (about 25 pages in javascript/*/property)
     Functions (about 50 pages in javascript/*/function or 
javascript/function)
     Methods (about 100 pages in javascript/*/method or javascript/method)
     Operators (about 40 pages in javascript/operators/*)
     Statements (about 19 pages in javascript/statements/*)

The rest are individual pages, no clustering at all needed:

     JavaScript Directives
     Errors
     JavaScript Reserved Words
     JavaScript Future Reserved Words

This single-topic / multiple-topic-clusters approach dictates that (if 
this line of reasoning is correct) all the pages are edited the same 
way.  That is, the same semantic form is used for all JS language 
pages.  If the JS language pages are fundamentally different in their 
layout, then this single-topic / multiple-topic-clusters approach is 
insufficient.

So how do we know about page layout?  We should have a hard look at the 
page formats of each potential topic clusters listed above.  In order to 
facilitate that, I performed an analysis listed below showing repeated 
lines of the format COUNT SECTION, listing every known section in all 
the pages, and counting how many times they occur.

I dividing the results into three segments, to discuss them later. Here 
you can see, for example, there are 279 pages with ==Remarks== sections, 
and 269 pages with ==Example== sections, and so on. Naturally the most 
used sections are candidates for templates:

FIRST SEGMENT
     279  Remarks
     269  Example
     249  See Also
     230  Parameters
     72   Return Value
     22   Exceptions

SECOND SEGMENT
     21   Properties
     20   Methods
     11   Constants
     8    Functions
     2    Examples
     2    Arguments

THIRD SEGMENT
     1    Syntax
     1    Statements
     1    Reserved Keywords
     1    Related Sections
     1    Related Reference
     1    Operators
     1    Objects
     1    Number Object Constants
     1    Modifying Properties
     1    Modifying an Accessor Property
     1    Modifying a Property on a DOM Element
     1    Modifying a Data Property
     1    Math Object Constants
     1    In This Section
     1    Future reserved words
     1    Example 2
     1    Example 1
     1    Errors
     1    Error Types
     1    Directives
     1    Data Property Example
     1    Assignment Operators
     1    Adding Properties
     1    Adding an Accessor Property
     1    Adding a Data Property

My thought is that we should: (1) create templates for each section in 
the first segment, (2) create autogenerated page listing to replace the 
sections in the second segment; and (3) wrap the remaining sections as 
one-off info or merge into some other section in the first segment.

We can definitely use semantic forms (templates) for the *first* 
segment.  Lots of pages have remarks, examples, parameters, etc. This is 
perhaps our best chance for a single *kind* of JavaScript element page, 
one that has all the first segment editable sections in it.

The *third* segment above we can rule out as page-specific information 
that doesn't warrant a semantic form.  There is only one page that ever 
uses any of those sections.  Those individual pages can be dealt with on 
a case by case basis, by merging the information into other sections 
like Remarks or something.

The amazing thing about the *second* segment is that (except for 
"Examples" which is just an "Example" and moved to the first segment, 
and "Arguments" which is really just a "Parameter" and moved to the 
first segment), every one of the second segment sections are simply a 
list of subpages within it.  Our wiki does that if organized correctly, 
so this is potentially a huge win!

As an example of autogenerating Properties, one newly imported page (the 
"Array" page) has a 'Properties' section that by just glancing at it, 
you can tell it is a listing of the subpages of Array that are the 
properties of Array:

     At http://docs.webplatform.org/test/javascript/Array
     ==Properties==
     The following table lists the properties of the '''Array''' object.

     {| class='wikitable'
     |-
     ! Property
     ! Description
     |-
     | [[javascript/Array/constructor|constructor Property]]
     | Specifies the function that creates an array.
     |-
     | [[javascript/Array/length|length Property (Array)]]
     | Returns an integer value that is one higher than the highest 
element defined in an array.
     |-
     | [[javascript/Array/prototype|prototype Property]]
     | Returns a reference to the prototype for an array.
     |}

Glance on the page for the other under Functions and Methods and you can 
see the same thing of listing of subpages.

The sweet realization is that these listings are easily autogenerated 
since the wiki already does it using Concept_Listing and API_Listing 
templates!  The templates even pull in the summary just like you see the 
manually entered summary above.  It is nearly an exact match, isn't that 
fortuitous?

To show show webplatform autogenerates subpages or topics or topic 
clusters, for example see how the apis page pulls in first-level 
subpages under "List of all APIs" when it codes Concept_Listing:

     At http://docs.webplatform.org/wiki/apis
     == List of all APIs ==
     {{Concept_Listing
     |Query=[[Category:API]][[Category:API_Listings]]
     |Use_page_title=No
     |List_all_subpages=No
     }}

Or see how the html attributes page under "Summary" when it codes 
API_Listing:

     At http://docs.webplatform.org/wiki/html/attributes
     {{Summary_Section|Index page for HTML attributes.}}
     {{API_Listing
     |Query=[[Category:Markup_Attributes]][[Category:HTML]]
     |Use_page_title=Yes
     |List_all_subpages=Yes
     }}

If we play our cards right, we can replace these "listing of subpages" 
sections (the second segment) with autogenerated equivalencies.

While I'm still learning when and where to use what template, and how it 
interoperates with topics and topic clusters, I do think the section 
analysis was fruitful.  In summary, I believe for all known sections 
that I've partitioned into segments, we should do templates for the 
first segment (or find similar things in the /apis/ pages we can reuse), 
merge the third segment into other places, and autogenerate the second 
segment.