How much should Querki establish *conventions*?

[jducoeur]

Okay, here's a broad question, looking for thoughts -- it's about Querki, but it isn't deeply technical.

I'm pondering the medium-term UI for Create Space. Currently, you just give the Name of the Space, but there's lots more metadata that we should be encouraging folks to enter in that window, including a less sucktastic UI for security (I believe we can boil the most common use cases down into a couple of radio-button sets), and an optional public description of the Space. (Eventually, Public Spaces will be listed on your Profile page.) This got me thinking about what the name of the Property should be for the public description. And of course, the obvious answer is, "Description".

I've been shying away from using simple descriptive Property names like that, in the interest of leaving the namespace (which, remember, is global across a given Space) as clean as possible for end users. But I wonder if that's the wrong way to look at it. It's very "programmer-y" to think that you should absolutely minimize the reserved words, but I'm beginning to suspect that a typical user would actually find it helpful to have a toolbox of consistent Properties, that are predefined so that we at least *tend* to have some consistency from Space to Space, instead of thinking of each one as its own special snowflake that you have to build from scratch.

I'm not thinking of anything terribly deep, just some extremely broad-strokes Properties that you can apply to any Thing or Model as seems appropriate. Specific examples that have already come up include:

-- Summary: a short Text Property, intended to be a one-line description of something.
-- Details: the counterpart to Summary, a Large Text that goes into more detail.
-- Description: technically similar to Details, but with a connotation that is somewhere in-between. More than a Summary, less than Details.

etc. I wouldn't go too hog-wild with these, but I suspect it would actually be helpful for me to just define some at the system level, use them myself and make them available for folks to use. I'd take things like the "Property Summary" Property, and switch that to just use the more broadly-defined "Summary" instead. Indeed, that was one of the inspirations here -- instead of having "Property Summary", "Type Summary", and so on, it seems to make more sense to just have a general "Summary" Property, that anyone can use.

(Technical note: this wouldn't technically consume namespace -- in theory, Spaces can override Names from Apps, so you could redefine "Summary" in your own Space if you wanted. But the intent is that 99% of the time, you would just use these standard Properties as-is.)

Opinions? This is one of those places where habits of a platform are different from those of a user-centric service, and Querki has aspects of both, so I'm not quite sure where to come down on it...

Comments

[kihou.livejournal.com]

I expect, if your target audience includes "ordinary people", that you want to prioritize making the common thing easy (but keep the uncommon thing possible). So, I'd expect that you'd want to figure out what common properties that will be useful in most spaces would be, and have those exist by default, but potentially have the ability to rename or replace them as appropriate (say, if we're localizing in Spanish, or I'm modeling something that has a pre-existing well-defined meaning of Description).

[jducoeur]

Hmm -- interesting point about localization. Low on the priority list for the time being, but I'll need to think about what the approach will be for localizing these conventions. (And indeed, localizing the common system Things in general.)

Renaming/aliasing is a good suggestion, and one I've pondered occasionally over the past couple of months. (Once I move out of early Alpha and need more user-API stability, I'll probably need to have an aliasing mechanism for any name changes at the System level, at least for a deprecation period.) This may be supporting impetus for me to deal with that...

[mindways]

Overall: yes. Not only for the type of direction you mention, but because people are going to be looking at the system source to learn how to use the system, and if everything uses names like Property Summary and Type Summary, users will name *their* properties Game Summary and Hand Summary, because, well, the extant Things do it that way so it's clearly the way to do things / a good idea, right?

-----

Side caveat: I hate systems which offer many different, poorly-differentiated "Description"-type fields, such that you either end up copy-pasting the same data between all of them (defeating the purpose) or having half of them be blank (causing various utilities like "automatically display all this stuff in [nice format X]" to fail).

(And the reverse-direction problem, of wanting to change what displays in a particular list, and not being sure which of umpteen properties you need to set.)

Can you come up with plausible situations where a Thing needs Summary and Description and Details? Are they common enough that you need to make it a convention, or can the convention just be Summary and Details?

[jducoeur]

The thing is, I expect Summary+Details and Description to usually be mutually exclusive, but I think that different use cases want one vs. the other, often driven by UI. For instance, I have clear reasons why Properties want separate Summary and Details. But that's probably too fiddly for the theorized Space UI, which just wants a single optional Description.

That said, it is possible that the default contents of Description could just be Summary + Details. So you can always *use* Description if you want the whole thing, and decide on a Model-by-Model basis whether you want to break that down or override Description itself...

[talvinm.livejournal.com]

As one of the less-programmery types playing around with it, I would love to have some Templates to work with. That sounds like what you are describing, at least in part: something that guides you to a common use for Querki, without breaking the underlying tools.

I fear I haven't been using it as much because I can't figure out how to use QL. The lack of a Tutorial is handicapping me rather badly at this stage.

Too, life is going nuts in the leadup to next week's Holiday. I have next week off, and I really hope to be able to spend some time playing with Toys. :)

[jducoeur]

As one of the less-programmery types playing around with it, I would love to have some Templates to work with. That sounds like what you are describing, at least in part: something that guides you to a common use for Querki, without breaking the underlying tools.

In this particular case it's less Templates and more Toolbox. What you're thinking of as a Template is closer to what I call an App, which will be coming in a few months.

I fear I haven't been using it as much because I can't figure out how to use QL. The lack of a Tutorial is handicapping me rather badly at this stage.

Understood, and sorry. The Tutorial got back-burnered when I realized that I need to rewrite the Editor first, to make things suck less, and other things have slowed down the Editor rewrite. (Although I'm making gradual progress there.)

The key, though, is to keep in mind that QL, like everything in Querki, is focused on making the really common things really easy. In particular, you can do an awful lot with just a simple reference:

* [[My Thing]] links to that Thing.
* [[My Property]] shows the value of the property, right here.

The other key is that QL is all about data transformation: "->" means "take the result received from the left, and provide it to the function on the right". Whatever is at the end of the chain gets displayed. So for one really common example:

* [[My List -> _bulleted]]

means literally "take the values in My List, pass them to the _bulleted function (which takes the received values and puts bullets in front of them), and show that".

Finally, note that you can nest Text inside QL inside Text inside QL, etc. Double-double-quotes means a nested Text. A Text inside QL receives each value, one by one. And ____ (four underscores) means "insert the whole received value here". So the spelled-out version of the previous example is:

* [[My List -> ""* ____""]]

That is, "take the values in My List and feed each one into this Text; the Text is a bullet, followed by the value". That is literally all there is to a bullet list. (_bulleted is just a more readable synonym for that Text.)

The Tutorial will be coming (and will be clearer than this, with a lot more examples), but if you happen to find yourself curious, just mess around with that formula: create Properties, feed them to chains of functions, and see what comes out. Look around with View Source on interesting pages (the Issues Space has some great examples, including its homepage and the Issue Model), and please ask questions -- it's useful for me to understand what needs more explaining. (I am *way* too close to this problem to have good perspective, so your questions might well help refine the Tutorial.)