Re: Generated related pages too generic

I think the "Related Articles" has a use, but it hasn't been used well, as
the "HTML" topic cluster clearly shows.  People (or import bots???) are
adding things to topic clusters without thinking about the impact on
"Related articles" list.

Adding more information to & rearranging that section of the editing form
might help.  The current structure of that part of the form is:

==See Also Section==
Most of this section is auto-generated by assigning an article to a topic
cluster. Only use Manual links rarely; instead add a new topic cluster to
Property:Topic_Cluster<http://docs.webplatform.org/wiki/Property:Topic_Cluster>
Topic clusters:{{{field|Topic_clusters|property=Topic_Cluster|list}}}Manual
links: (include bullet formatting but no section
head){{{field|Manual_links|input
type=textarea|rows=10}}}External links: (include bullet formatting but no
section head){{{field|External_links|input type=textarea|rows=10}}}Manual
sections: (raw other sections, including headers){{{field|Manual_sections|input
type=textarea|rows=10}}}

==Topics==

*See WPD:Topics <http://docs.webplatform.org/wiki/WPD:Topics> for more
information about these topics and how to add additional ones.*
Topics:{{{field|1|list|property=Topics}}}


A couple things to note:

* "Topic clusters" comes before "topics", and three large text boxes come
in between.  That corresponds to how it is laid out in the final page, but
when someone is filling out the form they will see (and fill out) the topic
cluster checkboxes before they see the topics checkboxes, so they are less
likely to contrast the two and think about their different purposes.

And that of course assumes that the contributor has read to the section of
the Editor's Guide [1] where the different purposes are defined.  Which is
a problem because:

*  Except for the link to the property page, there is no information in the
form about what topic clusters are and what effect they have on the final
page/see also section.  In particular, there is nothing to remind the
contributor that not only will they be adding related links to *this* page,
but they will also be adding this page as a link in all the other pages in
the cluster.


Moving the topics section ahead of the topics clusters would require
editing a lot of form templates and would have impact on the final page
structure.  But the other aspects can be tweaked:

1.  First, and most easily, use a more informative heading for the form
field.  Instead of just "Topic Clusters", how about explicitly saying
"Include this page in 'Related Articles' lists for the following topic
clusters".

2.  This is more debatable, but we could switch the form input type from
"checkboxes" to a multi-select drop-down list.  That would (a) emphasize
the difference between this section and the topics section, and (b)
encourage users to be stingy about how many clusters they select for each
page.  Downside is that it becomes difficult to select multiple topics when
they are appropriate.

3.  Make it easier to create *new* topic clusters from inside the form.
 (Currently, you can do it by following the link to the property page [2],
and editing that page to add a new allowed value.  But that possibility
isn't exactly clear.)  That would encourage contributors working on a set
of articles to create a narrow topic cluster that links a few related
articles instead of adding it to a broad concept.

    For example, I think the "disabled" attribute isn't really relevant to
a top-level list of "Related Articles on HTML".  Instead, it would be more
useful to have a list of related articles on "HTML Forms".

4.  Avoid the use of generic topic cluster names like "HTML" which conflict
with the topics names.  If a topic cluster should be used for top-level
articles on HTML, it should have a more meaningful name like "Introduction
to HTML" or "HTML Basic Concepts".  I'm not sure if this is easy/automatic
to update or whether it would be incredibly complex.  Either way, it
wouldn't solve the problem of too many existing pages being in the cluster.

    (In the meantime, if anyone shows up on IRC asking how they can help
edit webplatform.org without a lot of experience, you could suggest they go
through the topic cluster lists and uncheck top-level topic clusters like
"HTML" and "CSS" from minor reference pages!)

For starters, I've clarified some of the language on the topic clusters
property page, so that someone reaching that page has an easier time
creating a new cluster.  For the form template, I'd suggest something like:

==See Also Section==
Most of this section can be auto-generated by assigning an article to a
topic cluster.  By adding this page to a topic cluster, all the other pages
from that cluster will appear, grouped together, in the See Also list of
this page, and this page will appear as a link in those pages' See Also
list.  For that reason, you should avoid putting too many pages in the same
topic cluster.  See Topics and topic
clusters<http://docs.webplatform.org/wiki/WPD:Editors_Guide/step_6_author_or_upload_new_content#Topics_and_topic_clusters>
for
more information.
If there isn't a relevant topic cluster for an important concept related to
this page, you can add a new topic cluster to
Property:Topic_Cluster<http://docs.webplatform.org/wiki/Property:Topic_Cluster>
.
 If you want to add links to this page without including this page in a
topic cluster (e.g., to link to a main concept page from a minor page,
without creating a reverse link) use the Manual links section.

Include this page in 'See Also' lists for the following topic clusters:
{{{field|Topic_clusters|property=Topic_Cluster|list}}}

Until things get cleaned up (and topic cluster lists get trimmed down), I
would also support a re-arrangement of the See Also template to put the
manual links section ahead of the topic clusters lists.

--ABR

[1]
http://docs.webplatform.org/wiki/WPD:Editors_Guide/step_6_author_or_upload_new_content#Topics_and_topic_clusters
[2] http://docs.webplatform.org/wiki/Property:Topic_Cluster



On 21 April 2014 07:46, Jonathan Garbee <jonathan.garbee@gmail.com> wrote:

> The related pages links that are generated by selecting the checkboxes
> under "Topic Clusters" of the "See Also" section when editing are too
> general/broad. For example, on the disabled attribute [1] page I am seeing,
> * BGCOLOR
> * HTMLAudioElement
> * Pointer Events Primer
> * List
> * height
> * !doctype
> * dl
> * head
>
> etc. A bunch of almost completely unrelated things. Is there a reason that
> these are generated?
>
> I think it would be best to remove this generation of links in favor of
> simply having editors manually cross-link related things. That way we get
> higher-quality links that are known to be related in some way to the
> content at hand.
>
> Thanks,
> -Garbee
>
> [1] http://docs.webplatform.org/wiki/html/attributes/disabled
>