Plugin and Macro publishing standards

[TonyM]

Folks,

The social pressure placed on me with people like Mohammad and those of you beforehand publishing great content, is for me to publish more of my tools and utilities, has led me to build and automate a process to publish content.

I am starting this thread to solicit suggestions for such standards for publishing. I often see github, demo and source wikis published for a plugin. What should these contain?. My only published plugin  https://tiddlywiki.psat.com.au/mymenus/ is due for refactoring based on my new knowledge, but I received criticism for diverging from a simple empty tiddlywiki, which I thought was unfortunate, because I wanted to show case it well, and the empty wiki is not the most inspirational. But it's understandable people may find it hard to differentiate the presentation from the content of the solution itself, in "mymenus" case on install, almost nothing changes until you create menus (but few would realize this).

I am also addressing the workflow, so I have built a sandbox wiki standard from which to create a project name sand box wiki with designer tools included. My plan is to also use a tool to generate a demo or distribution wiki using a custom save, from such a sandbox wiki when the design is complete. The idea is to minimise the effort to do this well, be able to accumulate good practices into a work flow and make it easier to deliver solutions and more rapidly.

One of the issues here is I have a lot of wiki macro solutions that do not need to be plugins, they can be installed without save and reload so they can be "dropped" on any wiki and used, for exploratory purposes.

I can try and build me own solution but I would prefer to do so based on the wisdom and experience of the community so this post.

Issues such as these;

• Examples of this done well
• Fast track instructions to Github publishing so people can submit change requests against individual tiddlers in a solution
• What is on github - only tiddlers, the demo site ....
• The look and feel of demo and/or publishing wikis
• List of suggested standard practices (perhaps to grow over time)
• A way for consumers of a solution to nominate particular ones as an addition to the standard distribution
• The publishing and distribution of bundles and macros rather than plugins.
• What are best practices that should be used both in the solutions and posts on git hub announcing a solution (plus templates for such content)

Your feedback would be greatly appreciated.

Many of you excel at this so your advice and some de facto standards would be great.

Regards

Tony

[Mat]

I don't know if this is exactly what you're asking for but here are some "rule of thumbs" and other thoughts that have evolved in my own work:

Only show/serve what is relevant. This can definitely include a wide set of examples etc but it would mean that one generally sticks to standard TW behaviour such as default Theme, Palette, Storyview, tool buttons etc. 

I do deviate a tad from this by e.g activating "titles as links" partly because I think it is almost common courtesy to make it easy for people to fetch whatever they want from my public wikis, particularly when serving plugins. I've also disabled CamelCase linking because it is a nuisance with dead links.

Aslo I subtly, but noticeably, show what version the current TW has (above the tiddler title). IMO the user should get a feeling for the context the plugin was created in. ("Hm, this plugin seems to use some math stuff but 5.1.17 is pretty old... must be before the core math was introduced")

Continuing in this vein, I mostly avoid things that the visitor might mistake to be the plugin when it is not. One exception is my SideEditor which shows up as an arrow button in every tiddlers toolbar. I'm too lazy to remove it because I'd have to reactivate it whenever I want to tweak something. But other than this, typically no magic looking buttons or stuff that are not part of what is actually offered.

IMO, the very first tiddler meeting the visitor should, as a very first thing, state what the plugin does as succinctly as possible. For example: "FooBar is a plugin that lets you ...." or "BarFoo is a 100% CSS based stylesheet to get ...." (I note this is missing in your MyMenus plugin and hence a visitor can only guess, which probably minimizes the chances him trying it out). 

I typically name the wiki as the plugin (possible because I only serve one plugin per wiki) and I try to make the name as self explanatory as possible. The wiki subtitle is typically too short to allow for a description so often I allow myself some artistic freedom with some stupid joke or catch phrase for the plugin. 

I typically try to only have one default tiddler. If it is a complex plugin, I instead let this default tiddler have tabs such as "About", "Demos", "Notes", "Installation", etc. Those are just examples - exact tabs depend on the situation. It is fortunate if there can be a small enough demo to make it on first tab (i.e About or Intro) so the user can quickly decide if it is relevant at all. It is also nice if the 

I personally think it is nice to give provide some context for the creation such as clarifying its rationale and pointing out its possible weaknesses. That would probably be under a "Notes" tab.

Sometimes I include a list of the shadow or component tids with comments on what they do.

Sometimes I provide the plugin as a tag-pill, which is nice because it is so visual but also because a tag pill can allow drag'n drop of anything tagged so, not only the plugin components.

<:-)

[TonyM]

Thanks Mat that is very helpful,

Can I take it then that you only produce a single wiki for both the demo, documentation and plugin distribution?

Regards

Tony

[Mat]

Can I take it then that you only produce a single wiki for both the demo, documentation and plugin distribution?

yes. 

<:-)

[TonyM]

Mat 

When you set up a plugin as a tag-pill, does this mean you apply a tag to all plugin related tiddlers? This can import that tag to the wiki it is installed in, do you think this could be an issue?

Most of my projects are macros only so I tend to build them under $:/brand/project store them in a bundle (Marios) including the bundle tiddler itself. Is this acceptable?

I tend to place a list in the $:/brand/project that lists `[prefix[$:/brand/project]]` all related tiddlers. It would be nice to make that a draggable object.

I intend to publish my compilation of my Plugin and Macro publishing standards 

Including a way to generate the published wiki from within the design wiki.

Regards

Tony

Regards

Tony

[@TiddlyTweeter]

TonyM wrote:

The social pressure placed on me with people like Mohammad and those of you beforehand publishing great content, is for me to publish more of my tools and utilities, has led me to build and automate a process to publish content.

I am starting this thread to solicit suggestions for such standards for publishing. I often see github, demo and source wikis published for a plugin. What should these contain?

 ... 

One of the issues here is I have a lot of wiki macro solutions that do not need to be plugins, they can be installed without save and reload so they can be "dropped" on any wiki and used, for exploratory purposes.

I can try and build me own solution but I would prefer to do so based on the wisdom and experience of the community so this post.

I'm not sure my wisdom is orthodox :-). I'd say that JSON format is the premier format for sharing work, regardless of whether its a plugin or humble macro.

The plugin mechanism is very good for fact of shadow tiddlers & recuperation from change errors. The plugin format is also good for being consolidated, in the sense you can remove it in one go. The addressing contains it.

As I have mentioned before I think there is a social-psychological aspect to "plugins" that maybe sometimes inhibit breaking them down for reuse. Plugins are the work of an "auteur" and we respect that. Perhaps too much?

Best wishes

TT

[SylvainComte]

Hello all,

pretty interesting thread indeed. I'm not sure to be the most capable person on this subject but this last message reminds me of my first time developing plugin.

> Plugins are the work of an "auteur" and we respect that. Perhaps too much? 

Actually they are. Sometimes because of the "auteur" but in most cases in my humble opinion, because he's the only one that can fully understand what he did. Even when documenting the code, each author has a very own plugin structure. In my case, it has no consistency from one plugin to another. Just can imagine anybody looking at it would consider it's a mess...

I wish I had some kind of instructions about plugin structure, good practices (and bad ones) when I made the first (and the others) ;-)

I'm also aware that this is some very useful freedom for contributors. World is not black nor white...

> I mostly avoid things that the visitor might mistake to be the plugin when it is not.

I think this is a good practice I do not apply now. But i definitely shall (and will)

Speaking from macro, shouldn't they be "self-documented" ? For "classic" macro (i.e. non JavaScript) the documentation regarding usage parameters etc. could be directly included in the tiddler. Just as you have self documented functions in your favourite terminal function (`myfunction -help` you know)...

Cheers,

Sylvain

@sycom

[PMario]

On Thursday, September 12, 2019 at 7:30:23 AM UTC+2, TonyM wrote:

...

Most of my projects are macros only so I tend to build them under $:/brand/project store them in a bundle (Marios) including the bundle tiddler itself. Is this acceptable?

Bundles are intended to be "real tiddlers" that means, if you delete them, they are gone. ... I think this is a very convenient method to speed up a "project start". You can have a lot of predefined content, structure ... and so on, that is boring to type, because it's always the same.

For users it's much easier to delete stuff, that they don't need. ... That's what bundles are for!

------------------

Plugins will create "shadow tiddlers". You can overwrite them, but if you delete them, the initial shadow will survive.

-------------------

With Dynamic loading/unloading of plugins PR in the works, I think it will be interesting to "pluginify / unpluginify" a bundle.

have fun!

mario

[PMario]

Hi Tony,

I'm using 3 different repos to create my editions, themes and plugins. see: https://github.com/wikilabs

Since I'm using the TW environment variables, this structure makes it easy for me to develop the stuff.

I'm not 100% happy with the structure yet. There are some elements, which are error prone. ... BUT it's good enough for me.

To make it good enough for others, I'd probably need to polish it a little bit.

have fun!

mario

[Mohammad]

Hi Tony!

I myself use ThirdFlow + TiddlywikiPluginSkletone for creating new plugins!

It has some conventions and help you a simple workflow to create new publishable contents!

I have customized the skeleton with some macros, css and tools (like link-to-tab from wikilabs, tiddler commander, trashbin, todolist, status badge,...)

So, I tried to use some tools + rules to develop plugins!

For single to use macros, I developed Yazd which stores single or multi macros and one can simply download and use them (like drag and drop)

I think ThirdFlow from TheODrive (https://github.com/TheDiveO/ThirdFlow) is among the best!

Unfortunately TW documentation, best practices and good scripting style are missing! I personally expect to have good resources on thin on Tiddlywiki/dev

Best

Mohammad

[Mohammad]

The Mat stuffs are among the great resources in TW community!

I use 

• TW version like Mat on the title
• Single wiki per plugin
• Rather good documentation and examples (the most tedious part always ignored by developers)
• Examples as much as possible
• Try to keep them update with latest changes from Tiddlywiki
• Use GitHub to keep track of issues, history, feature requests (I absolutely do not recommend Tiddlyspot for this purpose)

Like Mat said, I believe your myMenu is very far from standrad (empty or tw5.com) and visitor confuses, keep it very close to empty edition!

--Mohammad

[Mohammad]

On Thursday, September 12, 2019 at 8:26:19 PM UTC+4:30, SylvainComte wrote:

Hello all,

pretty interesting thread indeed. I'm not sure to be the most capable person on this subject but this last message reminds me of my first time developing plugin.

> Plugins are the work of an "auteur" and we respect that. Perhaps too much? 

Actually they are. Sometimes because of the "auteur" but in most cases in my humble opinion, because he's the only one that can fully understand what he did. Even when documenting the code, each author has a very own plugin structure. In my case, it has no consistency from one plugin to another. Just can imagine anybody looking at it would consider it's a mess...

I wish I had some kind of instructions about plugin structure, good practices (and bad ones) when I made the first (and the others) ;-)

I'm also aware that this is some very useful freedom for contributors. World is not black nor white...

> I mostly avoid things that the visitor might mistake to be the plugin when it is not.

I think this is a good practice I do not apply now. But i definitely shall (and will)

Speaking from macro, shouldn't they be "self-documented" ? For "classic" macro (i.e. non JavaScript) the documentation regarding usage parameters etc. could be directly included in the tiddler. Just as you have self documented functions in your favourite terminal function (`myfunction -help` you know)...

This is quite true! Have a look at https://tw-scripts.github.io/Yazd/

Yes is a resource for single or small multi macros! Macro has a single tiddler with documentation!

NEVER forget examples more is better!

[Mohammad]

On Thursday, September 12, 2019 at 11:11:31 PM UTC+4:30, PMario wrote:

On Thursday, September 12, 2019 at 7:30:23 AM UTC+2, TonyM wrote:

...

Most of my projects are macros only so I tend to build them under $:/brand/project store them in a bundle (Marios) including the bundle tiddler itself. Is this acceptable?

Bundles are intended to be "real tiddlers" that means, if you delete them, they are gone. ... I think this is a very convenient method to speed up a "project start". You can have a lot of predefined content, structure ... and so on, that is boring to type, because it's always the same.

For users it's much easier to delete stuff, that they don't need. ... That's what bundles are for!

------------------

Plugins will create "shadow tiddlers". You can overwrite them, but if you delete them, the initial shadow will survive.

-------------------

I highly recommend plugin in these cases! Lets user overwrite your stuff but can restore them simply!

[Mohammad]

Mario,

 Some of your tools are quite handy and useful like link-to-tab which is a constant part of my development environment!

On Thursday, September 12, 2019 at 11:24:50 PM UTC+4:30, PMario wrote:

Hi Tony,

I'm using 3 different repos to create my editions, themes and plugins. see: https://github.com/wikilabs

Are these three repo are public? Is it possible to clone and see how they work? 

Since I'm using the TW environment variables, this structure makes it easy for me to develop the stuff.

I'm not 100% happy with the structure yet. There are some elements, which are error prone. ... BUT it's good enough for me.

To make it good enough for others, I'd probably need to polish it a little bit.

Yep!

 

have fun!

mario