Improve organization of the user contributed note submission area

[DrewAPicture]

I think we can improve the submission area for user contributor notes in some simple ways.

Currently:

1. All of the guidance information for submitting notes falls below the form. Some of this information would be useful to display before the form. Using the buttons for syntax-highlight are often lost on contributors. I think moving this text into view would be good.
2. All of the strings displayed alongiside the form are wrapped in paragraph tags which unfortunately doesn't allow anything to particularly stick out makes it easy to skim right over what might be useful information to have
3. The comment preview box that was added in #1865 feels kind of lost down at the bottom below the submission text and submit button. Moving it directly below the form seems like it might be more intuitive.

I've attached a patch that address all of the above, including introducing unordered lists, adding button-like styles around the code buttons text to make it clearer what it's referring to, and some other minor improvements.

See attached screenshots and patch.

[kevinwhoffman]

@DrewAPicture Great stuff. I agree moving the preview under the editor makes sense. I also like how some notes set the stage for the editing process, but I actually think all of the notes with the exception of the GFDL notice should be before the editor because they impact the subject matter and manner in which the note is written.

For example, the first bullet point under Submission Notes ("Please do not use this form for...") could head off potential off-topic notes before they are written if it appeared before the editor instead of after.

The second note ("In the editing area the Tab key...") explains how to use the editor, which is similar in nature to the third point up top ("You can enter text and code. Use php..."). Seems both of those would be beneficial to know before writing, so I'm not sure why one appears above and one below.

That leaves only the GFDL notice to appear after the preview. In that case it can be a standalone notice instead of a bullet point that notifies the user prior to submission.

As an alternative approach, have you considered populating the editor itself with placeholder text that communicates these notes while also demonstrating some of the shortcode usage? Doing so would alleviate the need for a separate bulleted list and cut down on the overall height of the section while giving the user a better idea of how the editor can be used.

[DrewAPicture]

Replying to kevinwhoffman:

@DrewAPicture Great stuff. I agree moving the preview under the editor makes sense. I also like how some notes set the stage for the editing process, but I actually think all of the notes with the exception of the GFDL notice should be before the editor because they impact the subject matter and manner in which the note is written.

The intent for leaving the spam, accessibility, and GDFL notices below the form was actually to place them directly above the submission button. The accessibility notice (tabbing out of the textarea) really should just be an aria-describedby field for the textarea.

As an alternative approach, have you considered populating the editor itself with placeholder text that communicates these notes while also demonstrating some of the shortcode usage? Doing so would alleviate the need for a separate bulleted list and cut down on the overall height of the section while giving the user a better idea of how the editor can be used.

Yes and no. What actually goes in the box is subjective, and while it certainly trends toward examples, we get all kinds of things submitted through there. I do think we could make the preview a little more intelligent actually. Do a simple regex for common JS and/or PHP and if the syntax tags are missing make the suggestion to add them.

I also think we could conceivably hide the preview box before anything is entered, or even go with a tabbed interface like GitHub​[1] and O2​[2] use.

[kevinwhoffman]

Replying to DrewAPicture:

I also think we could conceivably hide the preview box before anything is entered, or even go with a tabbed interface like GitHub​[1] and O2​[2] use.

I do like the tabbed preview on GitHub compared to O2 as it's more obvious. I'd be fine with tabs because preview is something I typically check just before publishing or as needed to confirm formatting. I don't think it's necessary to have realtime previews that constantly update like the comments on Trac do.

[keesiemeijer]

Adds a tabbed interface for writing and previewing user contributor notes

[keesiemeijer]

1905.1.patch​ is a complete workaround for the preview. It adds a tabbed interface for writing and previewing user contributor notes above the editor. The benefits of using tabs to update the interface is that less AJAX requests are needed. The tabbed interface can be re-used for other components.

A link to "Add Note or Feedback" is added to the ToC as well.

[keesiemeijer]

Write tab

[keesiemeijer]

preview tab

[kevinwhoffman]

@keesiemeijer Functionally this is a big improvement. Design-wise, the way the Write tab runs into the gray formatting bar is a bit awkward. This results in the Write tab feeling less cohesive than the Preview tab. I've attached a screenshot that I think makes the Write tab feel more like one unified component.

[kevinwhoffman]

Write Tab Contained

[keesiemeijer]

I agree, that looks way better. Can you add a new patch for the new style? (Or did you edit the image?)

[keesiemeijer]

Adds better editor styles

[keesiemeijer]

Write Tab Contained

[keesiemeijer]

In 1905.2.patch​ the editor styles suggested by @kevinwhoffman were added.

[keesiemeijer]

Only add editor styles if Javascript is enabled

[kevinwhoffman]

@keesiemeijer Thanks! Sorry I am still learning the process of submitting a patch.

[keesiemeijer]

No problem.

I found out it was a bit trickier than I thought because the editor includes its own stylesheet for the editor buttons.

[coffee2code]

What 1903.3.diff looks like on Chrome.

[coffee2code]

Re 1905.3.chrome.png​, diffs I've noticed from 1905.2.write-tab.png​:

• Use of -moz-use-text-color for border-color prevents Preview link's border from being initially transparent (mentioned in Slack).
• The toolbar and textarea don't look like they are inside a tab's page.
• The toolbar has a gray background.

@DrewAPicture also noted in Slack that he'd like to see the "Write" tab flush with the left edge.

Otherwise, looking great so far!

[keesiemeijer]

Update styles for Chrome

[keesiemeijer]

Chrome view of the write tab as in my dev environment

[keesiemeijer]

@coffee2code I hope removing -moz-use-text-color gives you the same view of the Write tab as in my dev environment.

[keesiemeijer]

@coffee2code

Other things I can think of is that the 'js' class is not added (in functions.php) to the body element as the background color of the quicktags toolbar (in your Chrome view) is not white as set in editor-style.css in the patch.

[keesiemeijer]

I've done some more testing and it seems the header used in my dev environment is different than the one used by wordpress.org. If I add the js class to the body class used by this theme it should also work in Chrome.

Another thing I've noticed is that the tabs are not displayed in single hook pages. This is because the Javascript dependency function-reference.js is not loaded for the wp-parser-hook post type posts.

It works and looks good in IE 8 an up.

[coffee2code]

In 3852:

developer.wordpress.org: Implement a tabbed interface for writing and previewing user contributed notes.

Also wraps form header in 'h3' tag so it appears in table of contents.

Props keesiemeijer.
See #1905.

[coffee2code]

In 5239:

developer.wordpress.org: Improve organization of the user contributed note submission area.

• Move some writing-related prefatory text into list above comment textarea
• Leave remaining submit-related text below comment textarea, but formatted as a list
• Add button-like styles around the code buttons text
• Minor string tweaks
• Ensure autoscroll goes to top of prefatory text and not just to the textarea

Props DrewAPicture.
Fixes #1905.