Re: JS page templates and topics (analysis)

Hey folks!

Thanks Max for all your descriptions and analysis about those pages. These
documentations are being really helpful to understand better the JavaScript
structure on WPD.

Following your words, we could in the first moment focus on one category of
pages, and finish it to move to the next one. As you suggested in the other
thread [1], I temporarily implemented some simple templates for those
cases, trying to advance some points, as you can see at the Array's page
[2] on the test docs.

After finish them, I started to wonder about the structure of each section
in the Objects page's category.

* Which sections should be include on the pages for this category?
* What kind of content should be inserted on those sections?

This is the kind of thing that need more than one single point of view, so
I will try to describe some suggested sections and their content based on
what we have at this moment and ask for some review and feedback about it:


*Summary*

** Section with a short explanation about the object.*


*Prototype*

** A basic sample of different prototypes to the object.*


*Parameters*

** A section with a description of each parameter displayed like the CSS
Properties Value's [3] section. This way looks more readable for me. What
do you think? Some of the pages display this content like tables, it could
be another good way to show them.*


*Examples*

** A section with a description and the code, following the CSS Properties
style [4]. To this section I have a question about the live sample,
code.webplatform.org <http://code.webplatform.org> doesn't support
JavaScript yet, should we keep the field to point to the live sample? Looks
fine to me keep it, once that soon our platform may support JS, it will not
be necessary update the Template and we could reuse the one that we already
have.*


*Constants*

*Properties*


*FunctionsMethods*

** Auto generated sections based on queries. *


*Remarks*

** This section contain general notes about usage, details and
observations. *

*1) Should we insert this section after the Examples or at the end of the
page?*

*2) What exactly is the content for this section?*

*3) Some pages have in the Remarks section some code snippets [5] [6] , and
no Examples section, should we split it or keep how it is?*


*See Also*
** Pages related.*

I hope that this short and not so complete approach could help us to define
a final model to the JS Objects page [7]. Please give your feedback, any
help will be really great.

Thanks!

[1] http://lists.w3.org/Archives/Public/public-webplatform/2013Dec/0075.html
[2] http://docs.webplatform.org/test/javascript/Array
[3] http://docs.webplatform.org/wiki/css/properties/display#Values
[4] http://docs.webplatform.org/wiki/css/properties/overflow#Examples
[5] http://docs.webplatform.org/test/javascript/String
[6] http://docs.webplatform.org/test/javascript/Array
[7] http://docs.webplatform.org/test/javascript/objects



Eliezer

@eliezerbernart
eliezerb


On Sun, Dec 8, 2013 at 6:14 PM, Max Polk <maxpolk@gmail.com> wrote:

>  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.
>
>