Manual-writing is instructive

[jducoeur]

There's nothing like trying to write a tutorial to show you where your system is still too complicated. I'm currently writing up "Querki for the Impatient", a reasonably flying introduction to the system, and am finding myself adding simplifying enhancements to the to-do list as I go. (The Name vs. Display Name dichotomy *clearly* needs reworking...)

Comments

[juan-gandhi.livejournal.com]

How about custom dictionaries?

[jducoeur]

Possible, but *way* down the priority list. Querki is more like a database than a word-processing system, so it's a less-crucial feature. And frankly, it's just plain hard -- Querki is a template system, mixing programming with text, so it's tricky to keep the two aspects straight at the edit time.

It's a good suggestion, and probably worth doing. But I suspect it's not going to happen until I have an entire staff of programmers, and can devote some serious time to doing it well. That's at least a few years off...

[gyzki.livejournal.com]

But I suspect it's not going to happen until I have an entire staff of programmers, and can devote some serious time to doing it well.

Programmers yes, and for manuals/tutorials in particular may I strongly recommend a writer/editor. Programmers who think that's the only skill they need, do not help a user who doesn't already know the answer.

[jducoeur]

Certainly true, but there reality wins out -- I can't afford to hire anyone, and I'm the only person who knows the system well enough to write the first manuals anyway. So for the first year, I'm pretty much stuck doing it myself. (Fortunately, I am at least better than most programmers at this, although I have my own unfortunate habits.)

Once I can afford to pay people to do stuff, you're correct that a professional writer would be helpful...

[querldox.livejournal.com]

On the other hand, I've always, even before becoming a writer myself, liked that for at least one Wolfram product, they wrote the manual first, before starting any programming.

[jducoeur]

I can respect that, if you have a clear enough idea of exactly what the end result is going to be. Querki is kind of intentionally the other way around, though: I'm experimenting and learning what does and doesn't seem to work in terms of workflow, and a lot is coming out significantly different from my original plans.

(Heaven knows, the QL language is coming out *way* more interesting than I'd originally expected -- achieving a decent measure of DWIM turns out to require a surprisingly powerful language...)

[mindways]

The Name vs. Display Name dichotomy *clearly* needs reworking...

Display Name vs. Display Text is also confusing.

(Are there any common circumstances where you use the Display Text for a Thing, but you're on a page for some *other* Thing? If that's not usual, I'd suggest switching Display Text to "Page Text" or "Viewed As Page" or "Page View" or something.)

[jducoeur]

Hmm. Possible -- I'll chew on that. It probably will *not* be terribly unusual to show a Thing's Display Text inside of another Thing -- once we get into user-defined Types I expect that to be somewhat routine -- but you may be right that changing the name to even something as descriptive as "Looks Like" might be helpful.

(I don't do that casually, since it will almost certainly break a lot of existing stuff. But if it's gonna change, it should do so soon...)

[mindways]

I don't do that casually, since it will almost certainly break a lot of existing stuff.

In the underlying Querki code, or in the Querki pages built thus far?

If the latter, perhaps add "rename property" refactoring capability? (If this is the last time you need to change what a Property name is, I'd be shocked. :)

"Looks Like"

That's confusing in an entirely different way - I expect it to be a comparison operator.

[jducoeur]

In the underlying Querki code, or in the Querki pages built thus far?

Mostly the former, which I'm less worried about (that's just a grep), but probably at least a bit in the latter (which is more hassle).

In the long run, this will become less of an issue, because Querki Explorer will replace name references with name-plus-OID references, which will be more durable. But that's just in the plans, and at least 6 months out. In the meantime, changes like this are a bit unfortunate, and not a trivial thing to do.

That's confusing in an entirely different way - I expect it to be a comparison operator.

Yeah, that occurred to me after I typed it. I'm not entirely in love with "Page View", but so far it may be the most accurate description...

[umbran.livejournal.com]

There's one thing that usually shows it better - usability testing.

[jducoeur]

Certainly true, although the same comment applies here as to gyzki's point -- it's going to be a sadly long time before I have any money to pay somebody to do it properly.

So for the moment, I'm stuck doing it very seat-of-the-pants, wedged in among a hundred other priorities pulling at my attention. When I *am* able to hire, an actual UX pro is on my list of the first five -- I think it's one of the more important positions for this project...

[umbran.livejournal.com]

it's going to be a sadly long time before I have any money to pay somebody to do it properly.

No, it isn't.

Go read "Don't Make Me Think", by Steve Krug. Then revise your plans.

The book is not long, and written in a pleasant conversational tone, so it goes by quickly. I submit you can't really afford to *not* do what Krug recommends, and what he recommends is cheap. I did it over at Harvard, and we gleaned a far more information than you would expect.

[jducoeur]

Hmm. Okay, thanks for the pointer...