Standardized Plugin Help

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.

Gocom · 2012-04-10 19:49:15

ruud wrote:

How does the suggested template aid in providing better plugin styling that works consistently across all themes?

Coins have faces too. How does styles provided by a plugin work consistently across all admin themes? That margin of 15 pixels look like nothing when the theme uses text sizes of 14px, and spacing relative to it. The plugin’s paragraphs/attribute lists lines are literally connected together.

Best help files I’ve come around have had background or text color set. Black on dark blue. I like that. And those yellow code blocks look so good on this textured sand background. That blue border from the theme, that yellow from plugin and that sand background.

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).

True. Textpattern needs something along the lines of CSS framework. Something that has different type of elements and selectors everyone can use, and provide consistent look/feel. This framework would then be forced by core and loaded no matter what admin-side theme is used. Themes could change certain aspects of it on selector basis, but there always would be a consistent framework to developers relay on.

Something along the lines of Twitter bootstrap, not necessarily by the looks, but functionality. The less styles everyone writes, the better.

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

I like to use paragraphs for attributes. Because of, well, spacing. Single attribute description can get long, and without proper spacing the content is hard to read. While to some it makes sense that visible is a boolean, others don’t even know what boolean means. Giving that origins story on bool is going to take few words.

Last edited by Gocom (2012-04-10 19:51:48)

philwareham · 2012-04-10 20:31:40

Yes, Ruud this thread was started four years ago and yet until I hooked that page into the wiki last week it was effectively buried out of sight and unused. I’m not saying it’s a perfect solution, far from it, but we need to take some initial steps to bring some order to the admin area. Feel free to amend it in the wiki if you see some improvements that need to be made.

I’ve already started documenting some design patterns for structural changes and a UI toolbox, but it’s going to take months of work – years maybe. So in the meantime I’m putting together a theme for use in Textpattern 4.5 that goes as far as I’m able to to improve UX within the structure we have right now. Jukka has been providing some really useful feedback on it and Stef has made some handy improvements to the admin code structure that help me get this theme made too.

Our users are going to expect Textpattern to work on their ‘post PC’ devices (sorry to use that phrase) going forward and the plugins inline styling we have now contain some huge barriers to that. The help pages seemed like a good place to start since some documentation already existed and it doesn’t rely too heavily on new UI elements being created.

ruud · 2012-04-10 22:28:23

Gocom wrote:

How does styles provided by a plugin work consistently across all admin themes? That margin of 15 pixels look like nothing when the theme uses text sizes of 14px, and spacing relative to it. The plugin’s paragraphs/attribute lists lines are literally connected together.

Exactly. Having an admin theme that makes it possible to create a pretty plugin help is a good thing. The reason I’ve used inline CSS wasn’t because I could, but because the default CSS resulted in lots of ugly (which, I admit, is highly subjective). I would’ve used the CSS provided by an admin theme if it were useable.

I like to use paragraphs for attributes. Because of, well, spacing. Single attribute description can get long, and without proper spacing the content is hard to read. While to some it makes sense that visible is a boolean, others don’t even know what boolean means. Giving that origins story on bool is going to take few words.

Spacing is style. A list of attributes is a list. You use paragraphs because the default styling of paragraphs gives you the visual effect you desire, while using an unordered list does not. Provide some nice styles for attribute lists and it will look just as nice (and makes a lot more sense semantically).

philwareham wrote:

Our users are going to expect Textpattern to work on their ‘post PC’ devices (sorry to use that phrase) going forward and the plugins inline styling we have now contain some huge barriers to that.

And it also causes problems if anyone ever wants to make plugin help accessible through textpattern.org.

I’ve already started documenting some design patterns for structural changes and a UI toolbox, but it’s going to take months of work – years maybe. So in the meantime I’m putting together a theme for use in Textpattern 4.5 that goes as far as I’m able to to improve UX within the structure we have right now.

Perhaps I’m misunderstanding, but these plugin help guidelines are not about improving style within the existing structure (because the existing structure is what plugin authors have put in the help part so far), but about defining how it should be structured. That’s fine. And makes sense, but if the main problem you’re trying to solve is to get rid of inline styling, then it requires a theme that fits with that structure and to be able to use that theme I expected to see some specific classes or other style stuff in the suggested structure for the plugin help. I do not see them.

If you’re saying the 4.5 admin theme will make plugin help look pretty, provided you stick to a proposed structure, then that would be a good reason to stop using inline styles (if the structure makes sense, semantically). But if it takes months/years before we can have some plugin help styles that work out of the box, then these plugin help guidelines seem premature and a step backwards from what is possible now with some naughty inline styling. Perhaps the Wiki should indicate to which future TXP version the guidelines apply to and that they’re a work in progress (for someone visiting the Wiki, it appears to be finished documentation).

Textpattern CMS

Textpattern CMS support forum

#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

#46 2012-04-10 19:49:15

Re: Standardized Plugin Help

#47 2012-04-10 20:31:40

Re: Standardized Plugin Help

#48 2012-04-10 22:28:23

Re: Standardized Plugin Help

Board footer