Standardized Plugin Help

Manfre · 2008-01-01 06:53:33

I agree with Mary.

net-carver · 2008-01-01 07:06:56

I haven’t really used screenshots in my help sections, but I think they might be useful.

Manfre and Mary are right; embedded shots are going to quickly kill your available space for copy. However, if they are included as links to images hosted on the author’s website then I think all should be ok: let the author decide if they are needed.

Edit: ~~Apart from the space limitation of the encoded plugin help, is there any other reason to discourage the use of images in the help section?~~ Ok, offline use of the plugin on development sites would be one obvious case. Any others?

Last edited by net-carver (2008-01-01 07:23:47)

Mary · 2008-01-01 08:19:27

Some folks have setups on their intranet (which means they also can’t access images from the internet).

I think if you want to have that kind of in-depth documentation (lots of text and images), it’s best if made available separately (HTML, PDF, Windows Help, etc), and just put the usual essentials in the help interface.

net-carver · 2008-01-01 12:28:20

Mary

yes, that sounds like a better idea.

hakjoon · 2008-01-02 01:37:00

Makes sense. Textbook could always be used too. One potential issue with separate docs is if an author’s site disappears and the in depth docs are hosted there the help docs could be lost.

Not a problem that needs to be solved here though.

net-carver · 2008-01-02 04:35:08

hakjoon

Following your aside for a moment: In that case, plugin authors could always issue the plugin as part of an archive (zip/gzip) which included something like a pdf file too. Even if their site were to disappear, anyone who downloaded the plugin’s zip file would probably still have a copy of the in-depth documentation.

Bloke · 2008-01-02 10:36:04

net-carver wrote:

plugin authors could always issue the plugin as part of an archive (zip/gzip) which included something like a pdf file too

Seconded. I’ve been doing something similar for a while and not had any complaints yet (or maybe people are too polite to tell me it’s rubbish).

I’ll be looking towards migrating my help to Manfre’s proposed system this year as and when I update plugins. I think I’ll keep a very cut-down, abridged (some might say zem-esque!) help in the plugin itself, with a link at the top to the full docs on my web site and a copy of said full docs distributed with the plugin as an html doc. If people would prefer a PDF, that’s not a problem either.

It’s a little extra work but seems the most robust solution imo and a compromise between my usual over-wordy docs/large plugin sizes and usability. Heaven forbid my site ever disappeared… what would the world do? ;-)

ruud · 2008-01-02 13:28:25

64kB of text should be more than enough to store plugin help for most plugins and is probably the most user-friendly way of providing plugin help, because it’s linked from the plugin tab.

If 64kB is not sufficient, I’d like to see an example ;)

I personally dislike the zip-files with separate documentation + plugin.

Bloke · 2008-01-02 16:15:07

ruud wrote:

64kB of text should be more than enough to store plugin help for most plugins and is probably the most user-friendly way of providing plugin help

I agree, but it doesn’t explain this. That’s just one of a number of issues I’ve seen for a whole bunch of plugins that work fine, then stop working for some people but work for others. When the help’s taken out they work. I just guessed it was a size issue but your recent post about having separate 64k areas for plugin and help stopped that train of thought dead. And it can’t be a server size limit that low, surely? 2Mb is the lowest I’ve ever seen a PHP install with. Really wish I could track it down. In the meantime I’m going to try compression and see if that fixes it, hoping that most people have zlib compiled in.

I personally dislike the zip-files with separate documentation + plugin.

Fair enough, you’re the first! I’ll stop doing it; saves me hassle as well. Not sure the best way to offer plugins that require a library though. Perhaps people should only find out about the library after the plugin’s installed? i.e. they must first go to the help screen, find the Installation section, click the link which then opens the .txt file from my server into the browser window for them to copy, open the plugin tab and paste? And also, what of .js files and .css files and required images etc? Should each be linked separately from the Installation section on the help screen for separate download?

I’m not being arsey, I really want to find the best way to distribute large plugins so it causes least inconvenience for pro users and best “isn’t TXP great” simplicity for newbies. Without zipping them up together, what’s the best way do you think? For reference, the next version of slimbox is probably going to have around 20 files in it so you can choose which lightbox method suits (jquery, or mootools, thickbox, slimbox, etc).

[ side note: it always kinda irks me that plugin (.txt) files by default open straight in the browser window wheras .zip get downloaded; I often forget to open them in a new browser tab. 95% of the time I want .txt files to open in the browser, but plugins I’d prefer to download because it looks amateurish to say “download the plugin” and you click, then get back a hunk of base64 on-screen. Yeah I know it can be changed in the browser prefs but then the other 95% of the time I’d be cursing it offering me the option to download .txt files that I wanted in the browser window. Bah! ]

ruud · 2008-01-02 17:40:44

That “Badly formed or empty plugin code” error is mostly a limit on the maximum size of a POST request that some webhosts have set to 64kB. That’s why compressing the plugin works. It doesn’t change the actual plugin; it only reduces the amount of data that is uploaded.

Not sure the best way to offer plugins that require a library though. Perhaps people should only find out about the library after the plugin’s installed?

I’d list the requirements at the download area. People should read the plugin help; that’s what it’s there for, so if a library is required, that’s a good place to mention it. The reason for having a library is normally to allow other plugins to use the same code, so it should be available separately. Bundling it often leads to old versions of the library being distributed.

And also, what of .js files and .css files and required images etc?

If they are small enough, you could consider making a plugin that self-extract itself within TXP so it auto-installs the static files and the ‘real’ plugin. If a plugin requires anything other than another plugin… is it still called a plugin? I always assumed plugins were self-contained.

plugin (.txt) files by default open straight in the browser window

Can’t that be changed by sending a different HTTP header?

thebombsite · 2008-01-02 20:22:21

plugin (.txt) files by default open straight in the browser window

In FireFox you can make changes in options. When I click on a plug-in .txt link my browser asks me if I want to view it or download it. Simple one-click choice.

obeewan · 2008-01-02 23:16:36

ruud wrote:

I always assumed plugins were self-contained.

I agree. A plugin should be self-contained. If it’s not it’s more of an add-on and most add-ons are a bit more complex to install then the “classic” plugin.

ruud wrote:

If 64kB is not sufficient, I’d like to see an example ;)

My advanced search plugin requires an external PDF manual, there’s no way I could have crunched that into 64kB. Maybe if I did a re-write of the code (again) it could be done a bit better. Hmmm … :D

Mary · 2008-01-02 23:48:19

I always assumed plugins were self-contained.

upm_quicktags. The reality is, some plugins (not all and not even many) simply can’t be self-contained.

Anyway, Ruud, we were talking about this + this when referring to separate plugin help.

obeewan · 2008-01-02 23:56:48

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

Bloke · 2008-01-03 00:02:14

ruud wrote:

That “Badly formed or empty plugin code” error is mostly a limit on the maximum size of a POST request

Ahhh, makes sense. I’ll offer a compressed option as standard from now on, thanks for clearing that up.

I’d list the requirements at the download area. People should read the plugin help; that’s what it’s there for

Agreed, and fair enough. I’ll certainly revisit this as I make updates, and rejig my horrible site and the entries at textpattern.org to make it uber-clear what’s what and what’s needed when. I’m such a slapdash hacker…

If a plugin requires anything other than another plugin… is it still called a plugin? I always assumed plugins were self-contained.

Didn’t realise that was the definition of a plugin, oops. I’d better rename most of mine then to… what is the official TXP nomenclature for plugins that aren’t quite plugins? Add-ons? I don’t want to mis-sell stuff.

The auto-install idea is interesting but probably out of my league right now. Most of my plugins to date require some form of styling and most rely on 3rd party js. Does this mean that anything using jQuery and any of its non-core-included subsidiaries (ui, dimensions etc) isn’t technically a pure plugin either?

@thebombsite

Thanks, and sorry for going OT here. Even though the dialog box with the radio buttons annoys me in FF (why they don’t offer 2 or 3 buttons for direct action is beyond me), where do you set .txt to do something else? In my prefs Content -> File Types -> Manage I don’t have a TXT file type listed and I can’t see a way of adding it in 2.0.0.11. Maybe I’m being thick.

Textpattern CMS

Textpattern CMS support forum

#16 2008-01-01 06:53:33

Re: Standardized Plugin Help

#17 2008-01-01 07:06:56

Re: Standardized Plugin Help

#18 2008-01-01 08:19:27

Re: Standardized Plugin Help

#19 2008-01-01 12:28:20

Re: Standardized Plugin Help

#20 2008-01-02 01:37:00

Re: Standardized Plugin Help

#21 2008-01-02 04:35:08

Re: Standardized Plugin Help

#22 2008-01-02 10:36:04

Re: Standardized Plugin Help

#23 2008-01-02 13:28:25

Re: Standardized Plugin Help

#24 2008-01-02 16:15:07

Re: Standardized Plugin Help

#25 2008-01-02 17:40:44

Re: Standardized Plugin Help

#26 2008-01-02 20:22:21

Re: Standardized Plugin Help

#27 2008-01-02 23:16:36

Re: Standardized Plugin Help

#28 2008-01-02 23:48:19

Re: Standardized Plugin Help

#29 2008-01-02 23:56:48

Re: Standardized Plugin Help

#30 2008-01-03 00:02:14

Re: Standardized Plugin Help

Board footer