Re: new plan to replace flags with Readiness Markers

This has been put on the back-burner for a couple weeks, but I've got a
bare-bones mock-up ready-to-go on the test wiki that I think meets all the
goals that have been discussed.

If I could get feedback on the structure & wording before Tuesday, then I
can start rolling it out on the main site.

There is still the possibility of making it prettier, with colour coding or
icons, and suggestions or comments are welcome.  (I think this is Jen's
domain...)  But getting it functional is the first priority.

We also need to come to a final decision about definitions of the different
states.  Specifically: should "In Progress" only be used if the article is
actively being edited, or for anything that is half done?  What defines
"Almost Done"?

The mock-up, without custom CSS, looks like [1]:

max-height

*This article is Almost Done*:
Find out more about article readiness
states<http://docs.webplatform.org/test/Property:State>,
or get involved to help make Web Platform Docs
better<http://docs.webplatform.org/test/WPD:Contributors_Guide>!
Already signed up? Go to the edit
page<http://docs.webplatform.org/t/index.php?title=css/properties/max-height&action=edit>to
find out what still needs to be done.
Things to note:

* It takes up a large chunk of real estate on the top of the page, but
remember that it will be replacing the big purple warning box [2].  The
extra text serves the same purpose as the warning box, but now it's on a
page-by-page basis instead of everywhere.

* As agreed in the teleconference of April 29 [3], if the state is marked
"Ready to Use", nothing prints out.

* Also as agreed, the status details field is not used at all on the final
page (View mode), but would still show up when editing the form.  The form
will also have a link to the Property page [4] with definitions of the
different states.

* The info text is the same regardless of state, all that changes is the
"This article is..." heading.

* The box uses the existing "Note" template, but the note is wrapped in a
div with a state-dependent class name, so we can target it later for
specific CSS (e.g. to match the colours and icons used on the home page).
 For Ready To Use articles, there is an empty div if we decide to add an
icon later.

  If you want to play around with CSS, the final structure created by the
templates is

      <div class="article-state State_Class"><div class="note">
            <p><b>This article is {{{State}}}:</b><br/>
                  Find out more...</p>
      </div></div>

  where State_Class would be one of Ready_to_Use, Almost_Done, In_Progress,
Coming_Later, or Unreviewed.

* For the test wiki, the above is currently encapsulated in its own
template [5], but for roll-out it would just replace the existing flags
template, and would appear on all pages that currently have the ability to
display flags.

And of course, the template is just the first step.  Once we get it up, we
still have to go through and review everything to assign a state!

...Amelia

[1]: http://docs.webplatform.org/test/css/properties/max-height
[2]:
http://lists.w3.org/Archives/Public/public-webplatform/2014Apr/0031.html
[3]:
http://lists.w3.org/Archives/Public/public-webplatform/2014Apr/0117.html
[4]: http://docs.webplatform.org/test/Property:State
[5]: http://docs.webplatform.org/test/Template:State





On 28 April 2014 20:54, Eliezer Bernart <eliezer.bernart@gmail.com> wrote:

> Hello,
>
> The topic will be discussed with more emphasis tomorrow in the meeting,
> based on the agenda topics. So let's wait for the final decisions and then
> we can make our moves.
>
> Thank you Amelia, for your efforts!
>
>
>
> Eliezer
>
> @eliezerbernart
> eliezerb
>
>
> On Sat, Apr 26, 2014 at 4:51 PM, Amelia Bellamy-Royds <
> amelia.bellamy.royds@gmail.com> wrote:
>
>> Hey Eliezer (and all),
>>
>> I've been playing around with the test wiki, trying to figure out a way
>> to get a "show details" set-up to work.
>>
>> One common approach is to use a hidden checkbox (so that the label of the
>> checkbox is the link, and a combination of :checked pseudoclass selectors
>> and sibling selectors is used to show hide content).  However, Mediawiki
>> converts any `<input>` tags to plain text, so that doesn't work.  Same goes
>> for `<details>`/`<summary>` tags, which also have the downside of not being
>> supported in many browsers.
>>
>> Another approach, which is slightly better semantically but which has the
>> side effect of jumping the scroll position, is to use a same-page link to
>> target the details and then use a `:target` pseudo-class to display the
>> content.  I've got that implemented in the test template [1], so that it
>> prints to the page like
>>
>>     *Page status:* <http://docs.webplatform.org/test/Property:State> Almost
>> Done Details...<http://docs.webplatform.org/test/css/properties/max-height#showStateDetails>
>>
>> Note that to avoid having two different links one after another, I've
>> removed the link on "Almost Done" and instead added a link to the "Page
>> status" heading.  That link goes to the property page [2], which I've
>> edited a bit to show my idea of having it as a useful reference page, with
>> definitions of the different property values and links to
>> search-by-property for each value.
>>
>> However, even in the test wiki I don't seem to have permission to make
>> the relevant changes to the common CSS file [3] to enable the show/hide
>> functionality.  It would need to be edited to add this block:
>>
>> div#showStateDetails:not(*:target)  #stateDetails{
>> /* hide if the browser supports the :target pseudoclass AND
>>     the showStateDetails target isn't active */
>> display: none; speak:none;
>> }
>> div#showStateDetails:target  #stateDetailsLink {
>> /* hide after being activated */
>> display: none; speak:none;
>> }
>>
>>
>> [1]:
>> http://docs.webplatform.org/t/index.php?title=Template:State&action=edit
>> [2]: http://docs.webplatform.org/test/Property:State
>> [3]: http://docs.webplatform.org/test/MediaWiki:Common.css
>>
>> -ABR
>> P.S.  I hadn't clued in to the fact that there was a full wiki copy for
>> playing around.  I'll know in the future not to dump sample code into an
>> email when I can create a functional sample page instead!
>>
>>
>> On 24 April 2014 22:07, Eliezer Bernart <eliezer.bernart@gmail.com>wrote:
>>
>>> Hey folks!
>>>
>>> Today I worked on the new State templates (our old Flags Templates) on
>>> test wiki.
>>>
>>> I followed some of the points talked today on IRC.
>>>
>>> So here is a Summary of what I did:
>>>
>>> a) Using the name "State" for the Semantic Templates [1][2] and
>>> Properties [3][4];
>>>
>>> b) Keeping the text field "State Details" in the semantic form [5]. It's
>>> really large, but we can easily resize it to any dimension;
>>>
>>> c) State is a Dropdown with only the allowed values in the semantic
>>> property State [3]. We still have a blank option, that I'm trying to figure
>>> out a way to remove, if someone know how to do, please update the template
>>> or let me know.
>>>
>>> d) The field "State Details"[4] will not be displayed in the form when
>>> the user select the option "Ready to Use" in the State field.
>>>
>>> e) On the document [6], it's being displayed the link to all the pages
>>> with the same State;
>>>
>>> f) I was not able to find a way to create the <a> tag and make a button
>>> to hide and show the div which has the content of the "State Details"
>>> section. If someone has any idea of how do that, please let us know!
>>>
>>> g) The "Flags" template [7] was removed from the form, and in that place
>>> included the "State" template [1].
>>>
>>> If I forgot something or you think that something need to be changed,
>>> please let us know! To see the changes you just need hit the edit button in
>>> any document [6].
>>>
>>> Thank you all!
>>>
>>> [1] http://docs.webplatform.org/test/Template:State
>>> [2] http://docs.webplatform.org/test/Template:State_Form_Section
>>> [3] http://docs.webplatform.org/test/Property:State
>>> [4] http://docs.webplatform.org/test/Property:State_Details
>>> [5]
>>> http://docs.webplatform.org/t/index.php?title=css/properties/max-height&action=formedit
>>> [6] http://docs.webplatform.org/test/css/properties/max-height
>>> [7] http://docs.webplatform.org/test/Template:Flags
>>>
>>>
>>>
>>> Eliezer
>>>
>>> @eliezerbernart
>>> eliezerb
>>>
>>>
>>> On Tue, Apr 22, 2014 at 3:52 PM, 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>
>>>>>
>>>>>
>>>>
>>>
>>
>