Standardized Plugin Help

hakjoon · 2008-01-03 01:36:19

obeewan wrote:
But still, if it can not be self-contained, is it a plugin still or have it evolved into an add-on?

Where does the distinction get made?

hak_tinymce is really an interface between TXP and tiny_mce so they can be distributed separately, the plugin is actually quite small, but I’m not sure that it’ the best approach as it would then require users to go and download tinyMCE and the image plugin, and install it all.

That being said I have been thinking about doing that so that i don’t have to keep updating the bundled tinyMCE version (which I am woefully bad at doing in a timely fashion)

obeewan · 2008-01-03 02:28:38

Where does the distinction get made?

Just take a step back and “feel” the words. Plugin. Addon. Looking on the meaning of the words this is my opinion what they mean (and do write back if I’m off the charts here).

A plugin; something you plug in to the software and we’re good to go. It’s all there, self-contained, nothing more needs to be added. Like back in the days when Microsoft added plug-n-play to Windows. The meaning of the whole concept was to just plug something in and then you’re ready to play (allthough it didn’t quite work that well out of the box, but that’s a whole different story).

An addon; something you add to the software but might require something extra to work, like for instance an css file, another plugin, a hack into the core or a library not included with the software and so on.

I’d love to hear your opinions on this.

thebombsite · 2008-01-03 03:09:33

@Stef – actually I was only half right. It depends on the link. If the link points directly to the txt file you simply get a chunk of Base64 thrown at you whereas if the link is a “download” you get the option provided that it is a txt file.

So I suggest that maybe all plug-in links should be downloads?

@Henrik – I’m with you on your definitions but what happens when you have a plug-in that is 2 plug-ins for example, zem_contact_reborn requires zem_contact_lang and there are a couple of others that have library plug-in requirements. So 2 plug-ins for the price of 1 but are they still plug-ins or are they add-ons.

Gocom · 2008-01-03 03:14:42

Henrik, I feel the same about those words. But unfortunately in terms of history they mean the same if being precise. Or that history of English and those words says.

something you add to the software but might require something extra to work

Extension – as it’s used commonly with softwares/programs and can be just part of bigger consistness. But because it means many things, it’s quite hard to use. So, word plugin in much better.

Cheers!

Last edited by Gocom (2008-01-03 03:17:12)

hakjoon · 2008-01-03 15:22:14

@Henrik – Your definitions make sense but I do kind of feel like in the end it’s really just semantics. I’m cool with either terminology but I do think Stuart has a point on the library plugin issue.

philwareham · 2012-04-01 10:56:18

Plugin authors don’t seem to be adhering to any standard as to how their help files display – and many are using inline CSS which should be discouraged.

To that end, I’ve rewritten this document to an extent in order to direct authors better. Let me know if you see any problems within it.

I think we also need another CSS rule or two in the core themes (Classic and Remora) so that plugin authors have all the display tools they need in order to get their help documents looking good. For example we need better display of code tags and pre tags like so:

code, .code {
font: 1.1em Monaco, "Courier New", monospace;
}

code {
border: 1px solid #e3e3e3;
padding: 0 .2em;
background: #f7f7f7;
}

pre {
overflow-x: auto;
border: 1px solid #e3e3e3;
padding: 1em;
background: #f7f7f7;
}

pre code,
.code code {
border: 0;
padding: 0;
background: none;
}

code.body,
code.excerpt {
border: 0;
padding: 0;
background: none;
}

Bloke · 2012-04-01 12:28:19

philwareham wrote:

I’ve rewritten Creating_Plugin_Help_Guidelines… to direct authors better.

Nice one, thanks. The only thing I don’t like about it — although this may be a personal preference — is the vast amount of scrolling past attributes that is required because of the paragraph tags in the attribute section. Although not perfect, I’ve started to model my attribute sections after the wiki, i.e. using a dl/dt/dd structure. I find it simpler to scan and also the markup is quite compact which means we can fit more into the (very limited) 64Kb text help space.

On the whole I concur with the proposed layout:

plugin name
key feature list
requirements / installation / uninstallation
usage (admin-side, plus any tags & attributes)
tag examples (unless examples occur in the relevant section about each tag)
changelog (optional, perhaps, when textpattern.org is up to speed, which has an implicit changelog & optional comments built in?)
optional licence
author & credits

Things like the changelog, while important, take up valuable space for documentation. Perhaps the space issue can be tackled by increasing the available text size from 64Kb? Then maybe we can get away with wordy markup.

The class names I agree should be standardised, but with the best will in the world nobody will stick to them if there’s no incentive to do so. Perhaps if the Help tab offered some kind of javascript folding and an automatic table of contents then it might provide such an incentive. After all, if an advanced user folds away the installation/uninstallation section because the author has used the h2(installation). class then the CMS could remember that setting across plugins.

Plugins that didn’t stick to the convention either do not benefit from automatically having the content folded, OR they could deliberately open up the section by using a different class name if, for example, there were any special instructions that even advanced users needed to know about. Perhaps we could specify some class names to use for different purposes, e.g. ‘standard’ installation (copy, paste, install, activate) vs a more specialised workflow.

Alternatively — and this is something .org could address — we don’t burden the plugin author with the simple installation instructions, deferring those to a known link, e.g. textpattern.org/plugins/installation. Or even to the wiki document. Advantages:

Newcomers who need to know can click it. And let’s face it, if you’ve got as far as reading the installation instructions there’s a 75% chance you’ve already got as far as copy/paste (unless you’re reading them on the author’s site before downloading).
Advanced users only have to skip over a single hyperlink instead of a wodge of text.
Authors don’t waste time including it.
If the basic core installation instructions ever change we can update just one document instead of 600 plugins.
Takes up less space in the help file

Another thing to do might be to offer a link in the plugin composer’s header block for each plugin. People who use the Composer then automatically get that for free and anyone who sees an unfamiliar block of Base64 can find out what to do with it by copying the link to their browser (I doubt the browser will autolink from a .txt file, but it might).

So there are probably a few simple baby steps we can take to make help files as useful as possible to a broad spectrum of users while not burdeining plugin authors with minutiae.

Thoughts / improvements anyone?

Last edited by Bloke (2012-04-01 12:31:34)

Gocom · 2012-04-01 13:03:22

All mine plugins use that type of structure as it’s now, but as classes go, I’m never going to add any type of classes, styles or IDs, or dates other than to the change log. And as Textile format goes, it for me needs to follow v1 as that is what other languages than PHP used as their Textile basis.

Plus, considering IDs and what not, help files itself are subject to namespace rules and collisions. Preferably anchors should be prefixed, and please avoid mixing any HTML with Textile. Either all HTML or all Textile.

Last edited by Gocom (2012-04-01 13:07:13)

philwareham · 2012-04-01 13:15:31

The classes were in the original document, I kept them there because maybe they related to something. I’ll do another revision later today taking into account your points above.

Bloke · 2012-04-01 13:22:35

Gocom wrote:

And as Textile format goes, it for me needs to follow v1

So no dl/dt/dd then… shame. The Composer of course doesn’t care because that uses the current Textile that’s in Txp but since you compile yours with a standalone version 1, it can’ t be helped.

Preferably anchors should be prefixed

Yes, that’s an issue. But if the classes / IDs that the plugin help viewer offers in its “acceptable” list are used by the author, the namespaces can be avoided on those elements. Any others should — as you say — be namespaced or prefixed.

Last edited by Bloke (2012-04-01 13:22:46)

Gocom · 2012-04-01 13:54:25

Bloke wrote:

So no dl/dt/dd then… shame. The Composer of course doesn’t care because that uses the current Textile that’s in Txp but since you compile yours with a standalone version 1, it can’ t be helped.

I don’t compile with standalone v1, but I don’t use composer either if you are referring to the plugin. A web editor has no way of cutting it and source control (git/svn) is essential, and so is splitting sources to multi-file structure. Going blind with just a web editor is… ugh. Matter of tastes I suppose.

The Textile requirement is just that the help file for me needs to be modular and work with the original Textile spec so that the file displays correctly on GitHub (and other systems) or on desktop application that probably isn’t using PHP.

Last edited by Gocom (2012-04-01 13:58:28)

ruud · 2012-04-01 14:09:09

Bloke wrote:

So no dl/dt/dd then… shame.

ul/li instead? It’s supported in textile v1 and makes more sense, semantically speaking, than paragraphs, although not as good as dl/dt/dd.

philwareham · 2012-04-01 14:49:32

OK, second pass on the document rewrite

Removed plugin date
Removed changelog – superfluous to help file and would be better served elsewhere (such as on the new Textpattern.org site)
Removed all class attributes
Made the anchor IDs more unique
Compacted the tag list so to reduce page length.
Textile formatting only.

Let me know if anything else needs to change.

Last edited by philwareham (2012-04-01 14:50:42)

makss · 2012-04-10 12:12:23

Maybe optionally add link to Plugin preferences?
It’s useful for me.

ruud · 2012-04-10 18:58:00

From the wiki:

Do not use inline CSS styling of your own – please make use of the existing CSS stylesheet that was provided by the admin theme instead.

I don’t know how the CSS is today on the plugin tab, but a few years ago it was pretty ugly. So yes, I used a block of <style></style> in the body to get something that was more pleasing to my eyes (probably not valid, but seems to work fine). How does the suggested template aid in providing better plugin styling that works consistently across all admin themes? Which ids/classes/styles can we rely upon to exist and be styled as expected in every admin theme? Is there some kind of “warning” class (bright red text, non-blinking though).

What’s the advantage of using “#help-section01”? Does that affect functionality or style? Is only the help- part relevant or also the section01 part? (to avoid renumbering, I’d avoid numbering styles)

The table of contents. Just list the h2’s there or also the h3’s? Otherwise, if you have a plugin that supplies a large list of tags, you need a separate table of contents at the beginning of the “h2. tags” section. Doesn’t the table of contents header get an id?

Removed changelog – superfluous to help file and would be better served elsewhere (such as on the new Textpattern.org site)

The same could be said about the summary and the license. You have to read them before installing the plugin. :)

p. %attribute_name% %value_type%
Description of the attribute usage.

How does this provide styling of the attribute list? Where do I put the list of valid values for this attribute? How do you differentiate between block tags, self-closed tags and tags that can do both? How do you indicate required attributes.

There has to be way to put the attributes in a list (ol/li!). Using paragraph tags doesn’t make sense.

Consistent, beautifully styled and complete inline plugin help is a nice goal, but I don’t see the benefits of rewriting existing plugin help content yet. I just see a lot of rules. Some make sense. Some are pretty arbitrary. This topic was started over 4 years ago. TXP.org now lists over 700 plugins. If you want to convince people to rewrite their plugin help content, it has to be more than rules. There have to be some advantages in doing it that way.

Textpattern CMS

Textpattern CMS support forum

#31 2008-01-03 01:36:19

Re: Standardized Plugin Help

#32 2008-01-03 02:28:38

Re: Standardized Plugin Help

#33 2008-01-03 03:09:33

Re: Standardized Plugin Help

#34 2008-01-03 03:14:42

Re: Standardized Plugin Help

#35 2008-01-03 15:22:14

Re: Standardized Plugin Help

#36 2012-04-01 10:56:18

Re: Standardized Plugin Help

#37 2012-04-01 12:28:19

Re: Standardized Plugin Help

#38 2012-04-01 13:03:22

Re: Standardized Plugin Help

#39 2012-04-01 13:15:31

Re: Standardized Plugin Help

#40 2012-04-01 13:22:35

Re: Standardized Plugin Help

#41 2012-04-01 13:54:25

Re: Standardized Plugin Help

#42 2012-04-01 14:09:09

Re: Standardized Plugin Help

#43 2012-04-01 14:49:32

Re: Standardized Plugin Help

#44 2012-04-10 12:12:23

Re: Standardized Plugin Help

#45 2012-04-10 18:58:00

Re: Standardized Plugin Help

Board footer