Making WordPress.org

Opened 9 years ago

Closed 8 years ago

Last modified 8 years ago

#1810 closed enhancement (fixed)

Better formatting for FAQ

Reported by: samuelsidler's profile samuelsidler Owned by: obenland's profile obenland
Milestone: Priority: normal
Component: Plugin Directory Keywords: has-patch
Cc:

Description

The current FAQ is fine but I think it could be improved.

Let's format the section in a special way (not the default, like Description), removing the "read more" entirely, and showing only the questions by default. Each one could be expanded to reveal the answer. Attaching a rough mockup of how this could look.

Attachments (4)

Screen Shot 2016-07-07 at 9.43.03 AM.png (56.1 KB) - added by samuelsidler 9 years ago.
1810.diff (1.5 KB) - added by obenland 9 years ago.
1810.2.diff (3.7 KB) - added by obenland 9 years ago.
1810.3.diff (416 bytes) - added by obenland 8 years ago.
Remove uppercase for FAQ dl elements

Download all attachments as: .zip

Change History (34)

#1 @ocean90
9 years ago

#1833 was marked as a duplicate.

This ticket was mentioned in Slack in #meta by sam. View the logs.


9 years ago

#3 @michaelarestad
9 years ago

Yes. Do exactly what that screenshot shows, but with a bit more elegant design patterns. :)

This ticket was mentioned in Slack in #meta by obenland. View the logs.


9 years ago

#5 @mapk
9 years ago

I've built a prototype of this FAQ here:
http://codepen.io/mapk/full/MeggqL/

It's pretty much inline with the mockup from @samuelsidler but with some minor spacing and padding details.

@obenland
9 years ago

#6 @obenland
9 years ago

I'd like to use a definition list to display FAQs, it makes it easier to manage the accordion and it's more semantic than headings/paragraphs.

@dd32 could you review 1810.diff? Can you think of a better approach?

#7 @dd32
9 years ago

The more correct method to do this would be to parse the FAQ prior to markdown occurring, which you can see in the upgrade_notice section above the proposed change in 1810.diff, I'm not entirely sure why screenshots are being parsed afterwards though..

You would then expose it as a Readme\Parser::$faq[ $question ] => $answer property on the object, CLI\Parser would then be responsible for storing it however you wanted, which could be a <dl> in the post content, or as custom meta fields (as we do with screenshots, etc).

Whichever way you approach it, it's worth remembering that not all FAQ's are using <h4>'s some use <h3> (members) and others use <strong> (share-this), some include free form data before the headings (wp-user-avatar), others (cookie-notice) just include a paragraph, and then there's those who use free-form "invalid" formats (wpremote &jquery-updater).

Those plugins were just me opening a bunch of random plugins in the database and looking at their post_content, I'd say it was a 50% hit rate on "edge cases" while looking for examples. Ignoring, truncating, or reformatting plugins like this is fine, we just need to plan that out before we parse stuff.

Last edited 9 years ago by dd32 (previous) (diff)

@obenland
9 years ago

#8 follow-up: @obenland
9 years ago

Second attempt: 1810.2.diff, it just uses the blob of text if it can't find questions.

I'm not sure how to mark it up properly and keep it in post content other than in Readme\Parser, given that the uploader uses it too?

This ticket was mentioned in Slack in #meta by obenland. View the logs.


9 years ago

#10 in reply to: ↑ 8 ; follow-up: @dd32
9 years ago

Replying to obenland:

I'm not sure how to mark it up properly and keep it in post content other than in Readme\Parser, given that the uploader uses it too?

Not sure how that's an issue myself.. If you duplicate stuff into the uploader from the parser, expect to have to duplicate new stuff over..

#11 in reply to: ↑ 10 @obenland
9 years ago

Replying to dd32:

If you duplicate stuff into the uploader from the parser, expect to have to duplicate new stuff over..

I don't, the uploader just passed the readme to be parsed.

This is the part I don't understand:

CLI\Parser would then be responsible for storing it however you wanted, which could be a <dl> in the post content

I assume you meant CLI/Import? So in the Importer you would take the Readme\Parser::$faq array and format it into a list there?

#12 @obenland
9 years ago

  • Milestone set to Plugin Directory v3 - M7

#13 @obenland
9 years ago

In 3825:

Plugin Directory: Accordion view for plugin FAQs

Includes a refactoring of plugin sections to be more modular.

See #1810.

#14 @swissspidy
8 years ago

Please do not shout at me :-( text-transform: uppercase; feels quite aggressive. Otherwise the accordion is :thumbsup:.

#15 @dd32
8 years ago

In 3827:

Plugin Directory: Readme parsing: When parsing the FAQ section, pull out any properly formatted (and some not-so-well-formatted) Question & Answer pairs to be displayed in a formatted fashion.

The primary method we support for FAQ entries is where the sub headings are the question, with the content following as the answer. Both = and # are supported for this:

=== FAQ ===
== Does the plugin do X? ==
Yes!
## What about Y?
Nah, Sorry!

As plugins have a wide range of contents at present, we also support plugins which have used bolded headingslike the following, note, that it must start and end the line with two asterisks.
This format isn't suggested for future usage, and is only included for the thousand or more common plugins which have used it.

=== FAQ ===
** Can I contribute to the plugin? **
Yes! Patches Welcome!

Finally, there's the plugin readme's who don't confirm to any of the above standards, or have included a paragraph of data prior to their Q&A's, for those plugins the freeform content will be prepended to the FAQ section and they won't get a properly formatted accordian-style interface.

Props obenland for the initial patch, a lot of subtle changes have been made to better handle the various readme's out there (and probably more tweaks are needed).

See #1810

#16 follow-ups: @dd32
8 years ago

@obenland Thanks for 1810.2.diff I decided to pretty much go in the same direction as you did there.

After a lot of tweaking of the functions to parse the majority of readme edgecase formats I could find, and also not breaking the parsing of the upgrade_notice for quite a few plugins I ended up with [3827].

For an example of what happens when there exists freeform data prior to the Q&A section, wp-table-reloaded is the first example I could find. In the event there's freeform data at the end of the Q&A, we have no way to detect that and include it in the last question.

Freeform data at present includes a lot of numbered and ordered lists, paragraphs directing people elsewhere, and even random non-FAQ material. I decided to just display that as-is anyway as parsing it wasn't really possible.
I'd suggest that the FAQ should get a readmore link added to it if no <dl> is present within the section - for consistency sake, and to prevent long FAQ's (which we can't parse) taking over the screen.

I'm going to kick off a job to reparse all plugins, it'll probably take a day or so to complete.

#17 in reply to: ↑ 16 @obenland
8 years ago

Replying to dd32:

wp-table-reloaded is the first example I could find.

Thanks for that, WP Table Reloaded is great bad example! :)

Once the job has finished we can close this ticket by removing the shim in wporg-plugins' functions.php.

#18 @mapk
8 years ago

After looking at the example here: https://wordpress.org/plugins-wp/jetpack/ we need to make sure the arrow icon aligns with the top line of the Question, even when the question is two lines.

Existing
https://cldup.com/OaLoMXs79M.png

Proposed
https://cldup.com/A2cMZHyMbI.png

Please do not shout at me :-( text-transform: uppercase; feels quite aggressive. Otherwise the accordion is :thumbsup:.

I think the uppercase works well here because it separates these questions stylistically from the other text on the page.

This ticket was mentioned in Slack in #meta by mapk. View the logs.


8 years ago

#20 @obenland
8 years ago

In 3828:

Plugin Directory: Top-align arrow icons with question.

Props mapk.
See #1810.

#21 in reply to: ↑ 16 @dd32
8 years ago

Replying to dd32:

I'm going to kick off a job to reparse all plugins, it'll probably take a day or so to complete.

Just to follow up, this completed a few days ago. @obenland can you remove any shims and make sure things seem right to you?

#22 @obenland
8 years ago

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

In 3834:

Plugin Directory: Remove FAQ shim after re-parsing of all plugins.

Fixes #1810.

This ticket was mentioned in Slack in #meta by obenland. View the logs.


8 years ago

#24 follow-up: @webdevmattcrom
8 years ago

Disagree that ALL CAPS works well there. They're really difficult to read like that. I'd prefer no text-transform, and the Blue accent color since they are links that have an action associated with them.

See screenshot here:
https://www.dropbox.com/s/3jq1jh42e778mz5/2016-08-24%2017_29_54-Plugin%20Directory%20%E2%80%94%20Free%20WordPress%20Plugins.png

I didn't dare re-open, but I think it's worth reconsidering.

#25 in reply to: ↑ 24 ; follow-up: @mapk
8 years ago

Replying to webdevmattcrom:

Disagree that ALL CAPS works well there. They're really difficult to read like that. I'd prefer no text-transform, and the Blue accent color since they are links that have an action associated with them.

I'm open to using Sentence case instead with these (it is easier to read). But I'm not convinced that the blue text is the best solution.

#26 in reply to: ↑ 25 @webdevmattcrom
8 years ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

Replying to mapk:

But I'm not convinced that the blue text is the best solution.

Perhaps 80% of the black text color then?

This ticket was mentioned in Slack in #meta by obenland. View the logs.


8 years ago

@obenland
8 years ago

Remove uppercase for FAQ dl elements

#28 @obenland
8 years ago

  • Keywords has-patch added

Added patch 1810.3.diff to remove uppercase for dl elements.

#29 @obenland
8 years ago

  • Resolution set to fixed
  • Status changed from reopened to closed

In 3928:

Plugin Directory: Use lowercase for FAQ dl elements.

Fixes #1810.

#30 @samuelsidler
8 years ago

  • Milestone Plugin Directory v3 - M7 deleted

Milestone Plugin Directory v3 - M7 deleted

Note: See TracTickets for help on using tickets.