WordPress.org

Making WordPress.org

Opened 3 years ago

Closed 2 years ago

#1905 closed defect (fixed)

Improve organization of the user contributed note submission area

Reported by: DrewAPicture Owned by: coffee2code
Milestone: Priority: normal
Component: Developer Hub Keywords: has-patch has-screenshots
Cc:

Description

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.

Attachments (13)

1905.diff (8.0 KB) - added by DrewAPicture 3 years ago.
1905_before.png (96.0 KB) - added by DrewAPicture 3 years ago.
1905_after.png (98.2 KB) - added by DrewAPicture 3 years ago.
1905.1.patch (23.0 KB) - added by keesiemeijer 3 years ago.
Adds a tabbed interface for writing and previewing user contributor notes
1905_write.png (47.3 KB) - added by keesiemeijer 3 years ago.
Write tab
1905_preview.png (69.9 KB) - added by keesiemeijer 3 years ago.
preview tab
1905-write-contained.png (19.5 KB) - added by kevinwhoffman 3 years ago.
Write Tab Contained
1905.2.patch (24.8 KB) - added by keesiemeijer 3 years ago.
Adds better editor styles
1905.2.write-tab.png (46.7 KB) - added by keesiemeijer 3 years ago.
Write Tab Contained
1905.3.patch (25.8 KB) - added by keesiemeijer 3 years ago.
Only add editor styles if Javascript is enabled
1905.3.chrome.png (20.5 KB) - added by coffee2code 3 years ago.
What 1903.3.diff looks like on Chrome.
1905.4.patch (27.1 KB) - added by keesiemeijer 3 years ago.
Update styles for Chrome
1905.4-Chrome-write-tab.png (30.7 KB) - added by keesiemeijer 3 years ago.
Chrome view of the write tab as in my dev environment

Download all attachments as: .zip

Change History (31)

@DrewAPicture
3 years ago

#1 follow-up: @kevinwhoffman
3 years ago

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

Last edited 3 years ago by kevinwhoffman (previous) (diff)

#2 in reply to: ↑ 1 ; follow-up: @DrewAPicture
3 years ago

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.

#3 in reply to: ↑ 2 @kevinwhoffman
3 years ago

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.

This ticket was mentioned in Slack in #meta-devhub by drew. View the logs.


3 years ago

@keesiemeijer
3 years ago

Adds a tabbed interface for writing and previewing user contributor notes

#5 @keesiemeijer
3 years ago

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
3 years ago

Write tab

@keesiemeijer
3 years ago

preview tab

#6 @kevinwhoffman
3 years ago

@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
3 years ago

Write Tab Contained

#7 @keesiemeijer
3 years ago

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

Last edited 3 years ago by keesiemeijer (previous) (diff)

@keesiemeijer
3 years ago

Adds better editor styles

@keesiemeijer
3 years ago

Write Tab Contained

#8 @keesiemeijer
3 years ago

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

@keesiemeijer
3 years ago

Only add editor styles if Javascript is enabled

#9 @kevinwhoffman
3 years ago

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

#10 @keesiemeijer
3 years ago

No problem.

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

This ticket was mentioned in Slack in #meta-devhub by drew. View the logs.


3 years ago

@coffee2code
3 years ago

What 1903.3.diff looks like on Chrome.

#12 @coffee2code
3 years ago

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
3 years ago

Update styles for Chrome

@keesiemeijer
3 years ago

Chrome view of the write tab as in my dev environment

#13 @keesiemeijer
3 years ago

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

#14 @keesiemeijer
3 years ago

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

#15 @keesiemeijer
3 years ago

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.

#16 @coffee2code
3 years ago

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.

This ticket was mentioned in Slack in #meta-devhub by coffee2code. View the logs.


3 years ago

#18 @coffee2code
2 years ago

  • Owner set to coffee2code
  • Resolution set to fixed
  • Status changed from new to closed

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.

Note: See TracTickets for help on using tickets.