WordPress.org

Making WordPress.org

Opened 6 years ago

Closed 4 years ago

Last modified 4 years ago

#156 closed enhancement (maybelater)

Allow ReadMe to support in-document links for h4s

Reported by: MattyRob Owned by:
Milestone: Priority: normal
Component: Plugin Directory Keywords:
Cc:

Description

Migrated from #wp24295:

The current Plugin ReadMe files use MarkDown syntax and over time these can contain a great deal of information for users, for example in the FAQs.

The length of these sections sometimes makes finding the part you need a case of trawling through the entire document or searching for words in the browser window and hoping you are using the same vocabulary as the ReadMe author.

I think a useful enhancement would be to add the capability to define in-document links to allow for things like a table of contents at the top of the FAQ section. Currently you can create a link in such a table like this:

[FAQ 1](#1)

But I cannot find a way to create the linked section later in the document as any HTML, name or id parameters seem to get stripped out.

If this is already possible, please can you tell me how to accomplish this and accept my apologies from opening a ticket.

Note this is already possible for some levels (like h3s, which are wrapped in ==), but not in other levels (like h4s, which are wrapped in =).

Change History (10)

#1 @mattyrob
6 years ago

  • Cc mattyrob added

#2 @dan.rossiter
5 years ago

  • Cc dan@… added
  • Priority changed from lowest to normal
  • Type changed from defect to enhancement

What is the status on this? I develop a plugin with a massive amount of configurable content which I have judiciously documented, but the documentation would be significantly more usable with the ability to add a table of contents.

The MultiMarkdown (http://fletcherpenney.net/multimarkdown/) syntax supports this functionality using [Header Name][], so maybe that's the best approach to stick with an existing standard.

If arbitrary header linking is not an option, maybe just allow for an optional auto-generated table of contents which would include all headers on the active tab.

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


4 years ago

#5 follow-up: @Otto42
4 years ago

  • Resolution set to wontfix
  • Status changed from new to closed

The current implementation of the readme.txt files does not support readme files much larger than about 10k to begin with, and even that causes major problems since the content of the readme.txt is sent as part of the API response.

Therefore, I would recommend NOT using the readme.txt for extensive documentation to begin with. Large changelogs should be moved out into separate files. FAQ sections should be limited to question for users *prior* to them installing your plugin.

Documentation on using the plugin should be contained within the plugin itself, possibly using the Help tabs built into WordPress or some other kind of explanatory screens in the admin. The readme.txt is not really the end-all be all of documentation.

As such, wontfix for now. Even in the future, when the readme.txt size limitation is removed, it will still be sent along in the API response, and so an arbitrary size limitation will likely be implemented. Probably about 8k or less.

#6 @dd32
4 years ago

  • Resolution changed from wontfix to maybelater

#7 in reply to: ↑ 5 @MattyRob
4 years ago

Replying to Otto42:

Therefore, I would recommend NOT using the readme.txt for extensive documentation to begin with. Large changelogs should be moved out into separate files. FAQ sections should be limited to question for users *prior* to them installing your plugin.

I agree completely with the principles of this but there are a couple things that have been missed:

  1. The current Readme example contains an FAQ header example - if it should not be in there then remove or amend that example.
  2. The WordPress plugin repository is a fabulous place to put code for others to use and all for free - as that is the case a good number of plugin authors do not have the time or money to launch a website of their own to host FAQs - so where exactly then are FAQs (and likely other things) supposed to be hosted? It's all well and good saying where they should not go - but where then should they be? They really should be with the plugin file.

I'm not disagreeing with the sentiment that it needs to be done different or better but the WordPress plugin community deserves something a little better - the front end of the repository has not changed in almost 10 years - perhaps it should be revised as in need of a little polish.

#8 @Otto42
4 years ago

There's nothing wrong with the FAQ section in the readme, all I'm suggesting is that you make the info there most useful for people who have not installed your plugin yet. That information is displayed to users pre-install, not post-install.

See, once a plugin is installed, then the documentation can be made available right in the plugin itself. The Help tab dropdown is likely the best place for that. Have the information right there on the plugin settings page, basically. Why force users to go somewhere else to find the information they're looking for?

I initially wrote about the Help tabs back in 2011, and while the underlying code has changed a bit (for the better), the basic principles remain the same:
http://ottopress.com/2011/new-in-wordpress-3-3-more-useful-help-screens/

#9 follow-up: @MattyRob
4 years ago

We may well simply be disagreeing over semantics then - but it still needs making clearer IMO.

FAQs are 'Frequently Asked Questions', it seems to me that the ReadMe FAQs should be called 'Pre-install FAQs'. FAQs are usually used for common troubleshooting and support questions - the kind of things that don't crop up before installation.

As a final point - although you clearly know all about the Help tab - in my experience a large number of WordPress users are not aware it's even there. They ask on a forum rather than looking about on their own screen! :)

#10 in reply to: ↑ 9 @Otto42
4 years ago

Replying to MattyRob:

As a final point - although you clearly know all about the Help tab - in my experience a large number of WordPress users are not aware it's even there. They ask on a forum rather than looking about on their own screen! :)

You're not wrong, but most plugins don't use it very effectively either. If you have good docs in it, stick a pointer to it or something on the page so it gets noticed. :)

Note: See TracTickets for help on using tickets.