Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Standardized Plugin Help
The help documentation is the biggest hurdle I face when creating plugins. All of my plugins have different layouts and styling with regards to the help documentation and it has always irked me.
It would be a good thing if there existed a template that all plugin developers could follow. This would make the process easier, more consistent and the end result would be much better for the community. It would also allow for the creation of plugin help generators and Textpattern Resources”:http://textpattern.org could host the plugin files and display the help documentation (consistently for all plugins).
The formatting should work without the class specific styles so it can gracefully degrade when only working with an unmodified textpattern.css.
The Sections of a plugin’s help documentation:- ToC (Optional)
- Summary
- Author Contact
- License
- Plugin dependencies
- Installation steps
- Uninstallation steps
- Tags (attribute descriptions and examples)
- Exposed functions (for class plugins)
- Global Variables
- Plugin Events
- Admin page help
- Examples (a large example that puts it all together)
The ToC and a tag index can be auto-generated when the plugin is encoded.
Textile Format:
h1(title). Plugin Titleh2(section). Section Name
p. Section text uses regular paragraph formatting
Section: Tags
All references to a plugin should use the class "tag". E.g. You must include %(tag)mem_awesome_plugin% on every page that...
Each plugin tag would have the following:h3(tag). prefix_tag_name
p(tag-summary). Description of the plugin tag and how it is intended to be used.
*(atts) %(atts-name)attribute_name% %(atts-type)value_type% Description of the attribute usage
* %(atts-name)attribute_name% %(atts-type)value_type% Description of the attribute usageSection: Exposed Functions
h3(tag) my_plugin_func
p(tag-summary). This function will do foo or bar.
*(atts) %(atts-name)Return Value% %(atts-type)return_value_type% Description of the function return value.
* %(atts-name)arg_name% %(atts-type)arg_value_type% Argument description.Section: Global Variables
h3(global). $my_plugin_global
p(global-summary). This array is set during _blah_ and is false on failure.Section: Plugin Events
h3(event). my_plugin.event
p(event-summary). This event is called when blah happens.
I will update the formatting as feedback is posted.
Last edited by Manfre (2007-12-29 00:17:33)
Offline
Re: Standardized Plugin Help
+1. Excellent idea. Many plugin’s have messed up help text.
Offline
Re: Standardized Plugin Help
Yep, works for me. Nice one Manfre.
Couple of points:
- I don’t think the otherwise awesome ied_plugin_composer accepts textile in the help, so a non-textile template might be required as well. I could be wrong
- The current plugin size limit includes help, yes? And quite a few people have had issues installing large plugins; when the help’s removed the plugin installs fine. Although it only assists a minority, I’ve started only giving a TOC or abridged help in larger plugins, with links to full online help. The plugin is of course distributed with a standalone .html help file in case the server is down. I’m sure this isn’t the best use of resources but it’s a workaround for the plugin size/max upload PHP limit. Further compression is an option I suppose (though I’ve no idea how to do it from ied_plugin_composer), but perhaps there should be an abridged template for massive plugins too? The full help, wherever it’s located, should follow the full style template as given above.
And, yes, I could probaly rationalise my plugin help quite a bit :-)
The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.
Txp Builders – finely-crafted code, design and Txp
Offline
Re: Standardized Plugin Help
Stef: the plugin size is has a 64kB limit for help and code separately, so help size doesn’t affect the maximum code size. Compression is usually enough to keep it below the upload limit of most webhosts.
Michael: I’d welcome the idea of having better default styling for plugin help, preferably similar to how Textbook styles the help pages for TXP tags. A few comments:- having examples all together works fine for small plugins, but for ZCR (which uses a similar, though slightly different styling than what you propose) I used an example for each tag because that was clearer, IMHO, than having one big chunk of examples.
- If a standard is decided upon, the
help-prefix for classes could be dropped. - I’d make the plugin title a H1 instead of H2.
- If there are installation steps, there may also be de-install/cleanup steps
Offline
#5 2007-12-28 14:36:22
- net-carver
- Archived Plugin Author
- Registered: 2006-03-08
- Posts: 1,648
Re: Standardized Plugin Help
Manfre
For larger plugins I think having an optional TOC at the head of page (and top^ links at the side of each major heading or entry in the TOC) might be useful too. I’ve also started including a hyper-linked tag index in my help. Smaller plugins might not need these items.
In summary, how about…
- Optional TOC
- Summary
- Author Contact
- License
- Plugin dependencies
- Installation steps
- Optional tag index (hyperlinks to tags)
- Tags (and attribute descriptions / example usage)
- Exposed functions (for class plugins)
- Admin page help
- Any other examples
I tend to put examples of tag usage in with the actual tags rather than at the end.
— Steve
Offline
Re: Standardized Plugin Help
net-carver wrote:
I tend to put examples of tag usage in with the actual tags rather than at the end.
This is much easier for users. I find myself looking at specific tags after a plugin is setup. Like in ZCR help – there is a quick setup at the beginning, and then tag examples after each tag. That works best in my view.
I also think an un-install option would be good, or instructions on how to un-install in case any forms etc were created.
Offline
Re: Standardized Plugin Help
@stef, plugins can be easily changed and adding support for textiling text is simple thanks to the textpattern/lib directory.
@ruud, Inline examples for each tag/function is good and I had that in mind. The examples section was intended more as a “the bigger picture” style example. E.g. a complete ZCR form, instead of just an individual tag. Dropping the “help-” prefix is a good idea.
@steve, I like the idea of ToC and tag index. If all of the sections and tags are identified by class, then these can be auto created when the plugin is compiled.
Offline
#8 2007-12-28 16:45:32
- net-carver
- Archived Plugin Author
- Registered: 2006-03-08
- Posts: 1,648
Re: Standardized Plugin Help
Manfre wrote:
@steve, I like the idea of ToC and tag index. If all of the sections and tags are identified by class, then these can be auto created when the plugin is compiled.
Ahah, if you’re heading down the auto-compilation of help sections route, then things could get very useful (I missed that in the OP, sorry.)
In that case you could pull some other information together automatically too like …
- the license and author contact details. Perhaps add a plugin[‘license’] field to the plugin template for that etc.
- dependencies on other plugins can also be detected by parsing the code block for required plugins or included files that are outside of the normal set of Txp files.
Also, couldn’t some variable substitution be done on a help section if it were in heredoc format inside the main php block in the template and simply echo’d out?
Just brainstorming a little here — so some of the above may seem way off the deep end.
— Steve
Offline
Re: Standardized Plugin Help
I added sections for “Global Variables” and “Plugin Events”.
Offline
Re: Standardized Plugin Help
The CSS styling is currently removed when a plugin is decoded. Here is a 4.0 patch
Offline
Re: Standardized Plugin Help
I’m all for it all since some of them I allready have in my plugins helppages :). Allthough all of them currently point to my old webpage that is no more. But next version and they’ll be fixed.
Great topic, good intensions!
Plugins: ob1_advanced_search 1.032b, ob1_search_score 1.0, ob1_pagination 2.5, ob1_title 4.1, ob1_modified 2.1
“Let your plans be dark and as impenetratable as night, and when you move, fall like a thunderbolt.”
— Sun Tzu
Offline
Re: Standardized Plugin Help
Manfre, excelent idea.
I suggest to add screenshots. Only in some documentation of plugins there is screenshots.
Offline