Standardized Plugin Help

Manfre · 2007-12-31 08:50:48

Screenshots and other media cannot be embedded within the help documentation and I think it would be best left as a link in the summary.

hakjoon · 2007-12-31 18:15:36

You can embed images if you encode them. I use it to show insert image vs insert thumbnail graphics in the inser hak_tinymce help.

Mary · 2008-01-01 01:42:02

Screenshots shouldn’t really be in there, unless: you have only one or two very small ones and they used to help explain something in the text. If encoded within your plugin, they could easily take up quite a lot of space which could be used by actual text, which I think should take far greater priority.

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! ]

Textpattern CMS

Textpattern CMS support forum

#13 2007-12-31 08:50:48

Re: Standardized Plugin Help

#14 2007-12-31 18:15:36

Re: Standardized Plugin Help

#15 2008-01-01 01:42:02

Re: Standardized Plugin Help

#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

Board footer