Re: new plan to replace flags with Readiness Markers

Some thoughts on implementation of the new status property:

* For displaying the status, how about a right-floated icon next to the
title (similar to the icon on the Summary header that indicates W3 status),
reusing the icons created for the home page?

As with the W3 status icon, the mark-up would contain a <div> with an
accessible text description of the status, and the icon would be subbed in
via CSS.

To make the float line-up correctly with the title, it would have to be the
first element in the article.  Although we could create a new template
section and add it into each page template, it might be easier to modify
the "Page Title" template and its corresponding form section template.  As
far as I've discovered, that template is used in every reference page
template, so changing it should update everywhere without having to go in
manually or create a custom script.  Downside is that it might not be
obvious that page status is part of "Page title".

* I don't know if it is straightforward to add a body class to the page
based on a Semantic MediaWiki property; I haven't come across anything
relevant while reading up on the system these past couple weeks.

My first though was to try to achieve a similar affect using sibling
selectors  -- if we have an element like the aforementioned icon at the top
of the page with a class set based on the property, then we can select all
the following headings or paragraphs and style them accordingly.  However,
there isn't currently a single block-level element we can select for adding
something like a coloured border down the side of the page.  The block
level element that contains the entire article (div#mw-content-text) is
created by the wiki server separate from processing any of the wiki content
for that page (and would be a parent, not a sibling, to any elements
created within the wiki code); the visual "page" that is drawn on screen is
a few steps up the DOM tree from that.

I think the easiest approach is to create a separate, absolutely positioned
pseudo-element to represent that type of graphical embellishment. With the
above-mentioned icon element in the page, all that would be needed is CSS
to
(a) set div#mw-content-text to position:relative,
(b) define a ::before or ::after pseudo-element on the status icon div, and
set it to be an absolutely positioned block with a negative z-index, height
= 100%, and a width such that it fits in the padding, and then
(c) create rules to set the background colour of that pseudo-element based
on the class of the status icon.

This approach could be used even without an explicit icon for page status:
create the page status span as above, but then use CSS to set it to zero
height and width/invisible text for visual browsers, and just use the
pseudo-element to show status.
However, I would warn against *only* indicating status via colour scheme;
someone arriving on a reference page with no experience of the wiki is not
going to understand that purple="to do" and cyan="ready to go"; and that's
even before we get into issues with accessibility and colour blindness.
 Icons give a bit of an idea of meaning, or at least encourage a new user
to figure out what they represent, but they should still have text to
complement them.  To avoid cluttering the page, the icon could have a title
tooltip with the relevant text, and a link to a page that contains more
information about the different page status values.

_________________________________________

So, to sum up with convenient cut-and-paste code, Amelia's recommendations
are:

< 1 >
Create Property:Page Status with type String and a list of allowed values
as per Jen's email, including useful descriptions of what each should mean
-- this is going to be the main reference page for the property.

< 2 >
Change Template:Page Title Form
Section<http://docs.webplatform.org/wiki/Template:Page_Title_Form_Section>

(
http://docs.webplatform.org/w/index.php?title=Template:Page_Title_Form_Section&action=edit
)
to:

<nowiki>{{{for template|Page_Title}}}</nowiki>
==Page Title==
{| class="formtable"
! Custom page title (leave empty for default):
| <nowiki>{{{field|1}}}</nowiki>
|}
==Page Status==
{| class="formtable"
! Status of this page (see [[Property:Page Status]] for information on the
options):
| <nowiki>{{{field|Status|values from property=Page Status|input
type=listbox|default=unknown}}}</nowiki>
|-
! Editorial Notes (describe any needed work or concerns):
| <nowiki>{{{field|Status Notes|input type=textarea|rows=5}}}</nowiki>
|}
<nowiki>{{{end template}}}</nowiki>


< 3 >
Change Template:Page Title<http://docs.webplatform.org/wiki/Template:Page_Title>

(
http://docs.webplatform.org/w/index.php?title=Template:Page_Title&action=edit
)
to:

<noinclude>
MediaWiki, by default, draws the h1 text (the page title) from the URL.
This is not appropriate for some of our page titles.

This template is used at the top of a lot of pages to effectively replace
that built-in H1 with something that can be overridden in the form. If
title is not provided, it will default to showing the last part of the URL.

The template also adds the icon indicating the [[Property:Page
Status|readiness status]] of the reference page.
<pre>
{{Page_Title
| <title>
| Status= <status string>
}}
</pre>
</noinclude><includeonly><!--

Readiness icon
--><div class="readinessStatus {{urlencode:{{{Status|unknown}}}|WIKI}}"><a
href="{{localurl:Property:Page Status}}" title="Status:
{{{Status|unknown}}}">[[Page Status::{{{Status|unknown}}}]]</a></div><!--

Page title
-->{{#if:{{{1|}}}|={{{1|}}}{{#set:Page_Title={{{1|}}}}}=|={{#titleparts:{{PAGENAME}}||-1}}={{#set:Page_Title={{#titleparts:{{PAGENAME}}||-1}}}}}}{{#set:Path={{PAGENAME}}}}<!--

Readiness notes
-->{{#if:{{{Status Notes|}}}| {{Note| {{{Status Notes}}} |title="Editorial
notes"}} }}</includeonly>

The first part uses the Status field to fill in class, title text, and
content text, with help from some MediaWiki variables [1].  It's a little
more complicated than Template:Standardization
Status<http://docs.webplatform.org/wiki/Template:Standardization_Status>
 (which
uses title attribute selectors instead of classes), but we don't want the
title-text associated with the pseudo-element of the <div>.

The second part is the existing code for printing out the correct title.
 Don't ask me to explain how it works.

The third part adds the editing notes if they exist, using the existing
Note template.  I like the idea of having them only show as a pop-up, but
not sure how to implement that practically, especially since I'm already
using the icon as a link to the status definition page.  I thought it might
be possible to use CSS to display the block for logged-in users, but there
doesn't seem to be a suitable class set on the page when someone logs in.
 It could still be done with a more complex if-block to test for user
status, if that's the preferred approach to dealing with the notes.

    [1]: https://www.mediawiki.org/wiki/Help:Variables

< 4 >
Add the following CSS rules to the main stylesheet:

#mw-content-text {
  position:relative;
  padding-left: 12px; /* leave room for the colour bar */
}
#mw-content-text.mw-content-rtl { /* reverse for rtl */
  padding-left:0;
  padding-right:12px;
}
#mw-content-text div.readinessStatus {
  float:right;
}
#mw-content-text div.readinessStatus a {
   display: block;
   color: transparent; /* don't draw text on visual browsers */
   /* set appropriate size and background sprite for the icon
      Note that the icon is the <a> element, not the div, so that the
entire area is clickable.
      (Still need the div, though, since the pseudo-element *shouldn't* be
clickable.)
  */
}
#mw-content-text div.readinessStatus.Ready_to_Use a {
  /* position the sprite to show the check icon */
}
/* (and the same for the other status values, using wiki-encoded versions
of the value as class names) */

#mw-content-text div.readinessStatus::before {
  display:block;
  position:absolute;
  top:0; left:0;
  width:4px;
  height:100%;
  z-index:-10; /* draw behind any siblings (although it should be in the
padding area, anyway) */
}
#mw-content-text.mw-content-rtl  div.readinessStatus::before {
  left:auto; right:0;
}
#mw-content-text div.readinessStatus.Ready_to_Use::before {
  background-color: /*cyan blue*/;
}
/* and again, repeat for each of the readiness classes */


< 5 >
Comment-out all the content in Template:Flags and Template:Flags form
section  (comment-out instead of delete, in case we ever need it again...).


The automatically set flags which are set in individual templates when they
are missing content would still work.  (E.g., "Needs Summary" is set by
Template:Summary Section, "Examples Needed" is set by Template:Examples
Section.)

_________________________________________


Finally, for those who missed the links on IRC after the Telcon, there is
already a page within Semantic Media Wiki that allows you to search for
properties with a specific value:
http://docs.webplatform.org/wiki/Special:SearchByProperty

It's fairly simple to use (especially compared to Special:Ask), and the
queries are sent via GET so that searches can be used as link targets.  For
example, you can get a list of anything currently flagged "Stub" via

http://docs.webplatform.org/wiki/Special:SearchByProperty?title=Special%3ASearchByProperty&property=High-level+issue&value=Stub

The one thing this search page *can't* do is find pages that *don't* have a
given property set (no luck trying to use it to find empty summary fields).
 Which makes it all the more important to introduce a default "unknown"
value for the status property via a template, so they can be tracked down
later.

(P.S.  to Jen: while you're cleaning up the Contributer's Guide, you might
want to look for an appropriate place to mention the Search by property
page.  Useful stuff, if someone knows that it's there!)

_________________________________________

Phew.  That was much more than I was planning when I started to write.
 That promised email on SVG will have to wait till later in the week.

--Amelia Bellamy-Royds




On 22 April 2014 12:52, Jen Simmons <jen@jensimmons.com> wrote:

> Ahhh! This email escaped from me before it was done!!
>
> I was about to write a section about the open text field:
> *      2) an open text field where editors can leave comments about what
> is needed. *
>           Rather than trying to organize information about what each page
> needs into a pre-fab list of checkboxes (that everyone has to learn about
> before it becomes accurate or useful), we decided to have an open box where
> people can write whatever is appropriate. "Needs an example". Or "I changed
> this foo thing, but I'm not sure. Will someone check it?" Over time if we
> see a need to have something more, we can add some kind of flag system
> later.
>
> We will use the readiness marker to also add a class to the body element
> of each doc page, like:
> <body class="almost-done">
> That way we can use the class to style the page however we want. We can
> put a colored stripe down the side of the page, or put a diagonal banner
> across a corner, or whatever. The body class alone provides everything
> needed to make the state of the page clear to the end user.
>
> We might want to consider adding the state to the text of the page as
> well, for accessibility reasons. We should think this through. It's not
> needed in cases where there is no screen reader.
>
> I'm hoping that having the readiness state clearly displayed on each page
> will
> 1) help improve the trustworthiness of our content, and
> 2) encourage people to help edit the content. If it says "almost ready",
> you can click & see in a clear box what's needed. Sign in, edit, change the
> state, and save — and when you save, the color coding state for the whole
> page will change. Exciting!!
>
> We also want to figure out how we can better make lists of things. I want
> to see all HTML pages that are Almost Ready. I want to see everything that
> was moved to In Progress last week, etc.
>
> Questions? Comments?
>
> Jen
>
>
> Jen Simmons
> designer, consultant and speaker
> host of The Web Ahead
> jensimmons.com
> 5by5.tv/webahead
> twitter: jensimmons <http://twitter.com/jensimmons>
>
>
>
> On Tue, Apr 22, 2014 at 2:44 PM, Jen Simmons <jen@jensimmons.com> wrote:
>
>> On today's call, we had a long and fruitful discussion about the flags on
>> the site, and the plan to change them. We revised the revised plan. Here's
>> what we decided:
>>
>> *A) Remove the mediawiki template that provides the current flag system. *
>>
>> This will keep the existing data in the database, but hide all evidence
>> of it. Flags will no longer be displayed on a page for a regular user, and
>> the flag form checkboxes will no longer show up for someone who's editing
>> the page.
>>
>> This will fix the problem that's been happening — people being scared
>> away from the site by a long list of RED THINGS that SOUND SCARY but are
>> actually quite hard to understand. Rather than trying to implement a
>> complex educational process to teach everyone what all those flags mean, a
>> decision was made long ago to simplify them. Today we realized rather than
>> replacing them with simpler editor-focused technical to-do-list terms, we
>> should be replacing them with end-user-focused information about the
>> quality of the content. Thus will will:
>>
>> *B) Add a "Readiness Marker" — two new fields to all Doc pages:*
>>
>> *     1) a drop down select with five choices: *
>>               > Ready to Use
>>               > Almost Done
>>               > In Progress
>>               > Coming Later
>>               > -unknown- (default)
>> *      2) an open text field where editors can leave comments about what
>> is needed. *
>>
>>
>>
>> There was a lot of discussion about the fact the current flags
>> kinda-sorta don't even work right now. If you click on a flag term, it
>> should go to a list of all content with that flag — and it doesn't. Of
>> course, as smart developers in the meeting people's started thinking
>> through how we could make this work... but a decision was made that this is
>> not a priority and we have other things that are more pressing to work on
>> (like getting the compatibility tables done). So we will *not* be
>> working on any kind of flag system that makes lists of content anytime soon.
>>
>> It was agreed that we do need better ways for contributors to find tasks,
>> and more easily find a set of pages to edit. We agreed that this should be
>> approached from a design perspective (let's first ask: what kind of lists
>> do people want? what kind of tools could be helpful? what is it people are
>> looking for?) and then come up with a plan to choose technology to fulfill
>> that need (which might include a new set of flags), instead of focusing on
>> the flags alone and forcing a solution that might not meet the needs at
>> hand.
>>
>>
>>
>>
>>
>> Jen Simmons
>> designer, consultant and speaker
>> host of The Web Ahead
>> jensimmons.com
>> 5by5.tv/webahead
>> twitter: jensimmons <http://twitter.com/jensimmons>
>>
>>
>