I’ve seen some very spartan readmes in the directory and wondered what best guidance is for README content in relation to plugins?
So not simply the minimum standard, but the suggested best standard?
The Plugin Guidelines and Theme Guidelines may answer your question. An example readme is added there as well.
1 Like
Thanks, so purely help/use /features advice? No changelog or anything like that?
Thanks, I’d looked at this, and it confused me a little.
If I wanted to keep a change log, that would be ok? I’m assuming yes, but, no readme.txt to put it in? my viewer looks at both files, though, I guess I can just copy the entire readme content over and that would be fine?
Apparently a readme and changelog is not required, according to the plugin/theme guidelines. Personally I think it should both be included in each plugin/theme (the changelog could be a separate file or be part of the readme).
Maybe a CP plugin/theme dev that is reading this has an opinion? Should we update the guidelines?
Plugins and themes can work without a readme, but it should be required for stuff that is in the CP Directory. And it’s best to include the changelog in the readme (or at least the most recent changelog info), as that file is used for displaying information in the CP Directory.
the readme and changelog are optional as my understanding is correct because the directory pulls info from the .md file. that said I would say it is importanto to put the changelog in the .md file exactly because that then shows on the plugin info page and people can see progression of the plugin.
that said, I use both - a readme txt and md and include changelog if applicable, at least in md.
You mean the README.md file. Pretty certain that CP and the CP Directory only require the main plugin file or theme file style.css and pull the headers from those files. So technically a readme is not required. But without it, the plugin/theme page in the CP Directory will be empty, except for the header info (version, etc).
I think at least the .md is mandatory exactly for that reason Guido, the plugin/theme page has to be populated.
In that case the plugin and theme Guidelines should be updated, I can do this, but I’m not the one that has the authority to decide to add this change to the docs.
1 Like
I think @Simone is the authoritative voice for the directory.
A README.md is a good practice but I think that it should not be mandatory as for easy plugins the description is enaugh.
Also a changelog is good, but git commits are a changelog if they have good titles and descriptions.
1 Like
If plugin or theme does not have a readme (.txt or .md), the CP Directory will use the description from main plugin file or theme file style.css, right?
Yes, there is also the description supplied when registering a new plugin in the directory’s form.
1 Like
With help from Simone some Guidelines have been updated, to make more clear that the readme is not technically required but (highly) recommended (for obvious reasons, such as providing additional info).
1 Like
I was a little shocked, when you said neither were required, as I’ve been looking into ways of translating and importing the contents for use as sources of in-admin help.
I’ve set myself a deliberately high bar in terms of the provision of help and accessibility for my solutions, and I like the idea of a single source of truth for help files, and some readmes are exellent, and its not too hard to split out the contents, using headings as dividers of content. I have an embrionic standard for doing that, in order to distribute the right kind of help to where it’s needed. And in standardised, accessible, localisable format, aimed at minimising an individuals cognitive load, when in potentially stressful situations.
But if they are optional, I guess I can forget about that. It’s unlikely that people will provide what is optional.
I’m actually all for flexibility. Having to provide a readme can be a significant barrier to entry, for a newbie.
Would you say that the majority of ClassicPress users are reasonably handy at coding? And is the target user base, including contributors, aimed at people already handy with code?
My experience is that most CP plugins and themes do have a README.md or readme.txt. If they don’t have that file included, the description from main plugin file or theme file style.css is used. So if you’re building something for this, you can use the same approach. Other headers (version, etc) will always come from main plugin file or theme file style.css.
1 Like
This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.