WordPress.org

Make WordPress Core

Opened 6 years ago

Closed 4 years ago

Last modified 4 years ago

#6362 closed enhancement (fixed)

Suggests for improving tech instruction

Reported by: RanYanivHartstein Owned by: westi
Milestone: 2.9 Priority: normal
Severity: normal Version: 2.5
Component: Inline Docs Keywords: has-patch
Focuses: Cc:

Description

2.5 introduced inline documentation in the administration areas - many options now have short descriptions.

However, some of these could be made superfluous if only the options they were documenting were properly explained in the first place.

For e.g., in the post edit page, the option for allowing pingbacks and trackbacks reads "Allow pings", and is followed by and explanation that reads "pings are trackbacks and pingbacks". Isn't it easier to just say "Allow trackbacks and pingbacks", and this way be more consistent with other mentions of these concepts elsewhere in the admin?

A more obvious example is in the link edit page. Options for setting the target value are just the meaningless "_blank", "_top" and "none", and these are followed by an explanation that reads "Essentially this means if you choose _blank your link will open in a new window" (i.e., "We confused you with too many options you don't care about, but this is how to get what you really want here"). I would suggest simply explaining what these options do - "_blank (new window/tab)", "_top (breaks out of frames), "none (same window)".

I suppose there are more examples, these are just a few that stood out.

Attachments (12)

6362.patch (8.0 KB) - added by ninjaWR 6 years ago.
6362.diff (8.0 KB) - added by Otto42 6 years ago.
Refreshed patch for trunk
6362.3.diff (2.1 KB) - added by ninjaWR 5 years ago.
6362.4-category.diff (1.3 KB) - added by xenlab 4 years ago.
Refreshing changes made in 6362.diff for trunk --> Doing one file at a time, but all will start with 6362.4* so that we know they are related.
6362.4-link-category.diff (731 bytes) - added by xenlab 4 years ago.
Refreshing changes made in 6362.diff for trunk. Description text was removed from this one. added it back in for consistency with wp-admin/edit-category-form.php
6362.4.diff (2.8 KB) - added by xenlab 4 years ago.
New version of 6362.4.diff (found more changes that had been moved into wp-admin/includes/meta-boxes.php) ---> Original attachment comment: Refreshed the changes made in 6362.3.diff for latest trunk (applies to wp-admin/includes/meta-boxes.php instead of wp-admin/edit-page-form.php now)
6362.4-tag.diff (758 bytes) - added by xenlab 4 years ago.
Refreshing changes made in 6362.diff for trunk. This one is for the edit-tag-form.php
6362.4-tags.diff (572 bytes) - added by xenlab 4 years ago.
Found another example of a description for a common field that didn't have the text changed in the original patch. Attaching this for consistency's sake.
6362.4-categories.diff (593 bytes) - added by xenlab 4 years ago.
More inconsistencies that original patch did not address.
6362.4-link-categories.diff (478 bytes) - added by xenlab 4 years ago.
More inconsistencies that original patch did not address.
6362.5-all.diff (8.3 KB) - added by xenlab 4 years ago.
Refreshed for 2.9-beta-1 r12212
6362.6-all.diff (8.3 KB) - added by xenlab 4 years ago.
Fixed i18n issue, and re-Refreshed for 2.9-beta-1 r12212

Download all attachments as: .zip

Change History (41)

comment:1 markjaquith6 years ago

Good points. Inline documentation is nice, not needing it is better.

comment:2 lloydbudd6 years ago

  • Milestone changed from 2.5 to 2.6
  • Summary changed from Inline documentation introduced in 2.5 to Suggests for improving tech instruction
  • Version set to 2.5

comment:3 ninjaWR6 years ago

  • Owner changed from anonymous to ninjaWR
  • Status changed from new to assigned

this sounds like something I can do

comment:4 RanYanivHartstein6 years ago

I opened a separate ticket #6615 that deals specifically with the link edit page issue. It includes a patch

ninjaWR6 years ago

comment:5 ninjaWR6 years ago

Patch takes care of some of the more obvious things... other than those, I didn't really see anything that I'd remove/change

comment:6 Otto426 years ago

+1, I noticed the "Allow Pings" one today, and thought that it seemed a bit silly.

comment:7 ninjaWR6 years ago

  • Keywords dev-feedback has-patch added

possible for 2.6?

comment:8 follow-up: RanYanivHartstein6 years ago

These are rather simple fixes, some related to #6615. Couldn't this be easily done in time for 2.7?

comment:9 in reply to: ↑ 8 santosj6 years ago

Replying to RanYanivHartstein:

These are rather simple fixes, some related to #6615. Couldn't this be easily done in time for 2.7?


Patch is most likely stale since it has been 3 months. Someone will need to update the patch and double check that the same areas need improvement.

Otto426 years ago

Refreshed patch for trunk

comment:10 Otto426 years ago

Patch seems relevant to me. Attached refreshed patch for current trunk.

comment:11 jacobsantos6 years ago

Can this get into 2.7? Are there any suggestions that would be holding this ticket back from inclusion into core?

comment:12 ryan5 years ago

  • Keywords has-patch removed

Stale patch. Removing has-patch.

comment:13 Denis-de-Bernardy5 years ago

  • Component changed from Administration to Inline Docs
  • Keywords needs-patch added; dev-feedback removed
  • Milestone changed from 2.9 to Future Release
  • Type changed from defect (bug) to enhancement

comment:14 ninjaWR5 years ago

Think this as slowly been resolved over the 15 months in the various releases. I'll take a look later when I have time before closing it.

ninjaWR5 years ago

comment:15 ninjaWR5 years ago

  • Keywords has-patch added; needs-patch removed

Latest patch brings the trackback/pingback wording for pages to the same as for posts. Also gets rid of the wording about the jankyness of the page ordering.

comment:16 scribu5 years ago

  • Milestone changed from Future Release to 2.9

comment:17 westi4 years ago

  • Keywords needs-patch added; has-patch removed

Patch has gone stale again :-(

If someone breaths some life into it soon I will commit.

comment:18 xenlab4 years ago

  • Cc xenlab added

working on refreshing 6362.diff changes for trunk now

xenlab4 years ago

Refreshing changes made in 6362.diff for trunk --> Doing one file at a time, but all will start with 6362.4* so that we know they are related.

comment:19 xenlab4 years ago

Page password protection was removed, eh?

xenlab4 years ago

Refreshing changes made in 6362.diff for trunk. Description text was removed from this one. added it back in for consistency with wp-admin/edit-category-form.php

xenlab4 years ago

New version of 6362.4.diff (found more changes that had been moved into wp-admin/includes/meta-boxes.php) ---> Original attachment comment: Refreshed the changes made in 6362.3.diff for latest trunk (applies to wp-admin/includes/meta-boxes.php instead of wp-admin/edit-page-form.php now)

xenlab4 years ago

Refreshing changes made in 6362.diff for trunk. This one is for the edit-tag-form.php

comment:20 ninjaWR4 years ago

  • Owner ninjaWR deleted
  • Status changed from accepted to assigned

xenlab4 years ago

Found another example of a description for a common field that didn't have the text changed in the original patch. Attaching this for consistency's sake.

xenlab4 years ago

More inconsistencies that original patch did not address.

xenlab4 years ago

More inconsistencies that original patch did not address.

comment:21 xenlab4 years ago

  • Keywords has-patch added; needs-patch removed

Patch is refreshed. I also found some inconsistencies that original patches did not address, and have added them here.

Apply these diffs:

6362.4.diff
6362.4-category.diff
6362.4-link-category.diff
6362.4-tag.diff
6362.4-categories.diff
6362.4-link-categories.diff

comment:22 scribu4 years ago

Cross-referncing: #11177.

comment:23 westi4 years ago

  • Owner set to westi
  • Status changed from assigned to reviewing

Will review and commit tomorrow.

xenlab4 years ago

Refreshed for 2.9-beta-1 r12212

comment:24 xenlab4 years ago

westi,

the patch has been updated for the latest in trunk. I've combined it in one file, which should make it easier to apply.

thanks for the commit!

  • Eric Marden

comment:25 dd324 years ago

<?php _e('Allow ') ?><a href="http://codex.wordpress.org/Introduction_to_Blogging#Managing_Comments" target="_blank"><?php _e('trackbacks and pingbacks') ?></a><?php _e(' on this page.'); ?>

This is going to be better written as:

printf( __('Allow <a href="%s" target="_blank">trackbacks and pingbacks</a> on this page.'), 'http://codex.wordpress.org/Introduction_to_Blogging#Managing_Comments');

Not all languages follow the same sentence structure as english does.

comment:26 xenlab4 years ago

I can see how that would be a problem. I've updated the patch with your suggested change.

xenlab4 years ago

Fixed i18n issue, and re-Refreshed for 2.9-beta-1 r12212

comment:27 xenlab4 years ago

Also if it was already entirely obvious, 6362.6-all.diff is the current patch to apply.

Thanks!

comment:28 westi4 years ago

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

I committed this in [12228].

I believe all these changes are in now.

comment:29 westi4 years ago

(In [12259]) Use _x() not _c(). See #6362 fixes #11228 props filosofo.

Note: See TracTickets for help on using tickets.