naming convention for TiddlyWeb Bags?

[simon mcmanus]

I'm interested in peoples thoughts on TiddlyWeb bag names.

At the moment there is a system bag which is used by the TiddlyWebWiki system plugins.

The TiddlyDocs system plugins currently sit in a bag called tdocs.  I want to change that to something more descriptive.

Something like:

tiddlydocs_system

This works for TiddlyDocs, but seems inconsistent with TiddlyWebWiki's use of the system bag.

The convention I am suggesting would prefix the bag name with the vertical name and the suffix would identify that the bag provides clientside functionality required by said vertical.

Proposed suffixes could be :

_application
_system
_UI
_app
_client

Would anyone object to such a convention being adopted by twebical and tiddlywebwiki? I think it will make things easier for people trying to understand how a TiddlyWeb vertical is put together if the system bag names are more descriptive about the things contained within them.


How would people feel about such a change?


Thanks

Simon

[Chris Dent]

On Nov 19, 2009, at 12:21 PM, simon mcmanus wrote:

> The convention I am suggesting would prefix the bag name with the
> vertical name and the suffix would identify that the bag provides
> clientside functionality required by said vertical.

This convention seems like it may be a bit premature. I can certainly
understand the desire for some naming conventions but it is important
to understand the multiplicity of contexts in which a vertical and/or
TiddlyWeb might be used. I'm also curious about what the conventions
are designed to allow or protect against? (more on that later)

TiddlyWeb is architected so that it is practically and conceptually
easy to reuse tiddlers in different contexts. Similarly it is
architected so that the same TiddlyWeb server can be used for multiple
things. It should be straightforward and possible to have TiddlyDocs,
TiddlyWebWiki and TiddlyGuv all from the same instance, being used by
lots of different users doing lots of different things.

Given that there are similar tiddler requirements for all the three of
the above, it makes sense to have (or at least allow for) having some
of those tiddlers in the same bag and reuse.

For example the ServerSideSavingPlugin would live in the bag currently
named "system" in TiddlyWebWiki and be available to all those
applications.

That current name may be the wrong one. I don't know. Yet.

So there's that. There's also this:

A part of the bag concept is that they can be used as named containers
for constructing stuff. For example one would have a TeamTasks bag
that contained all the tiddlywiki plugin, stylesheet and help tiddlers
that make up teamtasks. Then you would add that bag to a recipe that
includes another bag where tasks are stored.

So yes, having sensible names for bags is useful, but keep in mind who
you are making the names for and in what way are the bags going to be
used. You sound like you are hoping to have some conventions so that
it is easier for people approaching a vertical from the code side are
more capable of understanding what's going on. That's great and all
but leaves out what I think is the more important part: Giving names
and structure/content to the bags so that they are more capable of
being used by someone browsing around the TiddlyWeb server and
constructing recipes that allow them to have collections of tiddlers
that do the things they want.

> Proposed suffixes could be :
>
> _application
> _system
> _UI
> _app
> _client

What's the difference between application, system, UI and app? Are
they all required to make the thing go? If so, why not put them all in
the same bag so I can easily create a recipe that uses them but also
includes my own customizations? These names seem to optimize for your
use, not for the use of someone using the system.

To help me understand a bit more, can you describe what these names,
and using conventions at all, provides for you, other developers and
users of the system? What is being enabled and what is being prevented
(in the good safety way)?

> Would anyone object to such a convention being adopted by twebical
> and tiddlywebwiki? I think it will make things easier for people
> trying to understand how a TiddlyWeb vertical is put together if the
> system bag names are more descriptive about the things contained
> within them.

I think it is too early to be defining conventions like these. There
is, right now, only one packaged and installable vertical that is
getting widespread public use. That's TiddlyWebWiki. In some sense it
doesn't even count as a vertical because it is what is required to
make TiddlyWeb a serverside for TiddlyWiki. It's just one step off the
core.

What I would prefer to see is for convention to emerge, rather than be
prescribed. We have such limited informed use of the systems, thus
far, that if we made conventions now they would be born from ignorance
(ignorance of TidldyWeb and ignorance of how people use TiddlyWeb) and
fail to satisfy down the road.

For those of you that know me, this resistance to formalizing things
may seem contrary to my attitude about rigorously adhering to the HTTP
protocol and following RESTful principles. It's not: Formalizing human
processes is in a different kettle from formalizing how data is
handled in computer systems. We can predict computer systems very very
easily. Not so with people.

[Michael Mahemoff]

On Thu, Nov 19, 2009 at 1:24 PM, Chris Dent <chris...@gmail.com> wrote:
>
> On Nov 19, 2009, at 12:21 PM, simon mcmanus wrote:
>
>> The convention I am suggesting would prefix the bag name with the
>> vertical name and the suffix would identify that the bag provides
>> clientside functionality required by said vertical.
>
> This convention seems like it may be a bit premature. I can certainly
> understand the desire for some naming conventions but it is important
> to understand the multiplicity of contexts in which a vertical and/or
> TiddlyWeb might be used. I'm also curious about what the conventions
> are designed to allow or protect against? (more on that later)
>

As TiddlyWeb has been under development for 18 months and we now have
several verticals in production, as well as others that have been
under development a while, I think it's actually a great time to be
taking stock and coming up with some sensible conventions.

The conventions are primarily designed to make it easy for people to
learn from example, which in practice has been shown on most platforms
to be vastly more useful than learning from documentation. If
TiddlyWebWiki arbitrarily uses "system" and TiddlyDocs uses "tiddlers"
and TiddlyGuv uses "ui" for the same thing, we are not helping anyone
learn how to make a new application.

Furthermore, the conventions will help in conversations about
TiddlyWeb, aid in mining for patterns in TiddlyWeb applications, and
support tools such as an initial project generator and any
diagnositics tools.

It's great TiddlyWeb has many degrees of freedom, but the price you
pay for all this flexibility is people don't know where to start.
Conventions help to combat that problem so developers end up with the
best of both worlds. (The rapid "happy path" build-a-project-now
experience of Visual Basic with the rich, flexible, model of <choose
your favourite language/framework>).

> TiddlyWeb is architected so that it is practically and conceptually
> easy to reuse tiddlers in different contexts. Similarly it is
> architected so that the same TiddlyWeb server can be used for multiple
> things. It should be straightforward and possible to have TiddlyDocs,
> TiddlyWebWiki and TiddlyGuv all from the same instance, being used by
> lots of different users doing lots of different things.
> Given that there are similar tiddler requirements for all the three of
> the above, it makes sense to have (or at least allow for) having some
> of those tiddlers in the same bag and reuse.
>

I think the idea was to have prefixes for things specific to that
application. e.g. TiddlyGuv maintains licenses, so there might be a
bag called TiddlyGuv_licenses.

> For example the ServerSideSavingPlugin would live in the bag currently
> named "system" in TiddlyWebWiki and be available to all those
> applications.
>
> That current name may be the wrong one. I don't know. Yet.
>

The ServerSideSavingPlugin would be in TiddlyWebWiki_System (or some
other suffix); this makes sense if that project includes it and relies
on it for its core work.

> So there's that. There's also this:
>
> A part of the bag concept is that they can be used as named containers
> for constructing stuff. For example one would have a TeamTasks bag
> that contained all the tiddlywiki plugin, stylesheet and help tiddlers
> that make up teamtasks. Then you would add that bag to a recipe that
> includes another bag where tasks are stored.
>
> So yes, having sensible names for bags is useful, but keep in mind who
> you are making the names for and in what way are the bags going to be
> used. You sound like you are hoping to have some conventions so that
> it is easier for people approaching a vertical from the code side are
> more capable of understanding what's going on. That's great and all
> but leaves out what I think is the more important part: Giving names
> and structure/content to the bags so that they are more capable of
> being used by someone browsing around the TiddlyWeb server and
> constructing recipes that allow them to have collections of tiddlers
> that do the things they want.

I agree that's a vital goal. I'm not sure if I'd say it's more
important the ease of development, because boht are critical to the
success of TiddlyWeb; whichever you say is more important is arbitrary
depending on your perspective etc etc.

I don't see how sensible naming conventions make it harder to browse
the server though. I think it's useful if plugins are in a bag whose
project name is exposed. I don't think this is the case with things
like "comments"; you could argue plugins should be part of the bag
name too, ie you end up with "comments_comments", but I think that's
taking it too far and would indeed make browing more difficult.

Also, we already have the precedent that URLs in tiddlyweb are
designed by default for pedagogical purposes more than mapping what
most people would expect of a REST system in the real world. Hence,
http://examples.com/bags/docs/tiddlers/bid.html; instead of
http://example.com/docs/big.html.

>> Proposed suffixes could be :
>>
>> _application
>> _system
>> _UI
>> _app
>> _client
>
> What's the difference between application, system, UI and app? Are
> they all required to make the thing go? If so, why not put them all in
> the same bag so I can easily create a recipe that uses them but also
> includes my own customizations? These names seem to optimize for your
> use, not for the use of someone using the system.
>

This wasn't a very clear list; the idea is that we would probably use
only one of the above to describe the tiddlers that sit in the UI for
the application.

> To help me understand a bit more, can you describe what these names,
> and using conventions at all, provides for you, other developers and
> users of the system? What is being enabled and what is being prevented
> (in the good safety way)?
>
>> Would anyone object to such a convention being adopted by twebical
>> and tiddlywebwiki? I think it will make things easier for people
>> trying to understand how a TiddlyWeb vertical is put together if the
>> system bag names are more descriptive about the things contained
>> within them.
>
> I think it is too early to be defining conventions like these. There
> is, right now, only one packaged and installable vertical that is
> getting widespread public use. That's TiddlyWebWiki. In some sense it
> doesn't even count as a vertical because it is what is required to
> make TiddlyWeb a serverside for TiddlyWiki. It's just one step off the
> core.
>
> What I would prefer to see is for convention to emerge, rather than be
> prescribed. We have such limited informed use of the systems, thus
> far, that if we made conventions now they would be born from ignorance
> (ignorance of TidldyWeb and ignorance of how people use TiddlyWeb) and
> fail to satisfy down the road.
>

The argument is not that it's prescribed by the core TiddlyWeb
project, but that we start to discuss these conventions, and that a
canonical app will be developed to demonstrate them. As I said above,
I don't believe it's too early to start struggling towards a set of
conventions, so that new projects coming on can adopt them and see how
we go, instead of everyone having to start from scratch.

[Chris Dent]

On Nov 19, 2009, at 4:21 PM, Michael Mahemoff wrote:

> As TiddlyWeb has been under development for 18 months and we now have
> several verticals in production, as well as others that have been
> under development a while, I think it's actually a great time to be
> taking stock and coming up with some sensible conventions.

It is always a good time to be taking stock and coming up with
sensible conventions. No dispute there. I just have concerns that the
discussion is insufficiently informed. My response on the "prime time"
thread may point out better where I think some of the misunderstanding
happen to be:

http://groups.google.com/group/tiddlyweb/msg/976c406f81156ae6

As I've stated a few times, I have nothing against conventions and I'm
very interested in making things easy to learn by example[1].

> I think the idea was to have prefixes for things specific to that
> application. e.g. TiddlyGuv maintains licenses, so there might be a
> bag called TiddlyGuv_licenses.

But what if that bag of licenses is also useful for my application
which is running on the same TiddlyWeb server? If it is called
TiddlyGuv_<something> does that mean I'm not supposed to use it? In
this sense what I am is a user of the TiddlyWeb server (not the
installer/admin) and I'm cruising through the list of bags (via a web
interface) wondering what's there and what I can make use of.

> I don't see how sensible naming conventions make it harder to browse
> the server though. I think it's useful if plugins are in a bag whose
> project name is exposed. I don't think this is the case with things
> like "comments"; you could argue plugins should be part of the bag
> name too, ie you end up with "comments_comments", but I think that's
> taking it too far and would indeed make browing more difficult.

Sensible naming conventions aren't in doubt. What's in doubt is the
sensemaking being used to come up with those conventions. Maybe it is
correct, we don't yet know. What I'm saying is that I think, based on
what I've read so far, that there is more to understand (to make sense
of) before we consider the conventions we are thinking about to be
sensible.

> I agree that's a vital goal. I'm not sure if I'd say it's more
> important the ease of development, because boht are critical to the
> success of TiddlyWeb; whichever you say is more important is
> arbitrary depending on your perspective etc etc.

Not to me its not (arbitrary). As a developer I have the luxury to far
more information about the structure of the application, the
installation, and the instance than a "user" does. If I want under the
lid, I just look. The user can't do that. So yes, it is a matter of
opinion, but the opinions aren't flights of fancy. My opinion is that
stuff, i.e. information, should be addressable and reusable. That's my
fundamental number one design goal with TiddlyWeb.

> Also, we already have the precedent that URLs in tiddlyweb are
> designed by default for pedagogical purposes more than mapping what
> most people would expect of a REST system in the real world. Hence, http://examples.com/bags/docs/tiddlers/bid.html
> ; instead of http://example.com/docs/big.html.

This seems an orthogonal tangent and is also wrong.[2]

I'm sorry if I seem horribly resistant or something like that. I'm not
resistant to naming conventions in any fundamental way, I just think
discussing the topic _now_ is putting the cart before the horse. At
the moment I can't sit down on a fresh computer and install--in the
normal Python ways--and run multiple instances of any other TiddlyWeb
vertical than TiddlyWebWiki. Until we cross that threshold we're
jumping ahead.

Yes, I admit, the current state of affairs requires a good deal of
understanding of Python tropes, memes, idioms etc. That's unfortunate
but true. We're at that stage. That's just the way it goes. Down the
road a TiddlyWebWiki vertical creator won't need to worry about those
things, but right now we can't, as a group, just ignore them. We don't
have that luxury yet. That's for the people who come next.

[1] Despite evidence that people don't actually go look at the
existing examples.
[2] Describe to me how recipes and bags are disambiguated in your
scheme while still maintaining a robust complete naming scheme with
Cool URIs that adequately supports access to both individual entities
and aggregates thereof, doesn't require extensions or query strings
and preserves browsability via human URL construction. I'm curious to
see it.

[FND]

I'd echo Chris's sentiments here, and currently do not have anything to
add to his elaborations.

So I'll settle for an explanation of why TiddlyWebWiki's client-side
plugins are contained in a bag called "system".
This was a conscious decision because of the frequent use of "system" as
a prefix in the TiddlyWiki universe. This means that anyone familiar
with TiddlyWiki could pick up TiddlyWebWiki and easily derive the
purpose of that bag.

However, in the context of a vertical building on top of TiddlyWebWiki,
shipping with its own plugins, this assumption of a particular target
audience might not be valid anymore.
I would argue that it's perfectly reasonable for the same set of plugins
(TiddlyWebAdaptor, ServerSideSavingPlugin etc.) to end up in a different
bag then. In fact, it might only be a subset of TiddlyWebWiki's plugins,
as diff'ing, for example, might not be relevant (not to mention version
requirements) - so it's selective reuse of the individual components
rather than reuse of the TiddlyWebWiki client as a whole.


-- F.

[simon mcmanus]

Thanks for the responses everyone,

I strongly suspect that any bag naming format used in TiddlyWebWiki and TWebical will become the naming convention used by the majority of TiddlyWeb projects. Not because we explicitly define them as conventions but because that is the bag structure people will copy when they create their own TiddlyWeb verticals.

So maybe I should be try to explain my confusion with the naming/use of the system bag:

Fred Said :

"So I'll settle for an explanation of why TiddlyWebWiki's client-side plugins are contained in a bag called "system". This was a conscious decision because of the frequent use of "system" asa prefix in the TiddlyWiki universe. This means that anyone familiar with TiddlyWiki could pick up TiddlyWebWiki and easily derive the purpose of that bag."

So should the system bag contain all TiddlyWiki plugins tagged systemConfig? If I naively attempt to follow the existing convention I would put all TiddlyDocs TiddlyWiki plugins in the system bag? Is that right? What happens when I want to use a different theme or interchange another bit of clientside code?

It seems inevitable that I will want to maintain separation between the client side functionality of my different TiddlyWeb verticals. The existing convention seems to imply all tiddlers tagged systemConfig should sit in the system bag.


Thanks

Simon

2009/11/19 FND <FN...@gmx.net>

--

You received this message because you are subscribed to the Google Groups "TiddlyWeb" group.
To post to this group, send email to tidd...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/tiddlyweb?hl=.

--
Simon McManus

blog : http://simonmcmanus.com

[FND]

> I strongly suspect that any bag naming format used in TiddlyWebWiki and
> TWebical will become the naming convention used by the majority of
> TiddlyWeb projects. Not because we explicitly define them as conventions
> but because that is the bag structure people will copy when they create
> their own TiddlyWeb verticals.

That assumption seems somewhat unfounded.
I would think that as things evolve, higher-level verticals like
T{Guv,Docs} become canonical references for this purpose.

> So should the system bag contain all TiddlyWiki plugins tagged
> systemConfig? If I naively attempt to follow the existing convention I
> would put all TiddlyDocs TiddlyWiki plugins in the system bag?

It appears you didn't quite get what I was trying to say in my previous
posts - but I'm not sure how to further clarify those points.
Basically, I'm suggesting that your vertical might not have TWW's
"system" bag at all. Instead, it could just ship with TiddlyWebAdaptor
and ServerSideSavingSavingPlugin in the tiddlydocs bag.


-- F.

[Ben Gillies]

Perhaps this is a good use case for setting a description on all system/vertical related bags.

The system bag might therefore come with a description something like:

    stores the TiddlyWiki plugins that trigger saving to TiddlyWeb

whilst the tdocs bag in TiddlyDocs might be:

    contains all default required tiddlers for the TiddlyDocs vertical to work

Instead of setting up specific naming conventions, this may be somewhat easier, and more descriptive.



Ben

[rakugo]

Ben ++