InfoQube IM - Community

Submitted by JJSlote on 2009/08/26 13:40

We've been discussing the idea of a Tutorial IQBase. New users seem to be having a rough time of it. The existing sample puts a newcomer in the thick of an HTML manual, loaded with overview and theory. And the Blank leaves him pretty much on his own. Our user needs something a little friendlier, an interactive walk through the capabilities of IQ, and some help with the mechanics.

Update: The "Welcome" grid has been relocated for markup to:

http://www.sqlnotes.net/drupal5/index.php?q=node/1007

Discussion should remain in the present thread.

Anyone interested, please contribute your thoughts, edits, concise writing, and proposed sequence of subsequent grids.

Rgds

Jerome

Comments

It's a good idea and I like it.

Just a few quick notes before I think about it a bit more:

[quote]"You'll notice there are only two fields displayed front and center: the # field [...] " [/quote] : new user sometimes have a hard time figuring what/where "fields" are exactly. Yes, strange, maybe. You could write : "You'll notice there are only two fields (shown as columns in the grid) displayed front and center: the # field [...] "

or something like that.

[quote]"Press Enter twice to create your new Item" [/quote]: why twice ?

Also, when keyboard shortcut is mentioned, we/you could/should mention that there are almost always mouse and menus items equivalents (et : right click on any item offers ways to create items, sub items, etc.). (We could also refer to the corresponding manual section, without getting into too many complexities...)

>>: why twice ?<<

Hi Armando

Yep, I wrestled with that wording, and initially went with "once or twice." IQ's precise behavior here depends on an Options setting under Grids: "When Editing, Enter creates a new item." I had that option checked for about a day, but blank items proliferated. Another problem is that we don't know where the new user has clicked. If it's in the center of field:Item, then she is editing and may require the second Enter. If she clicked on field:#, she'll press Enter only once. But we can't explain all that yet. Hedging and digressions in a tutorial are a major turn-off. The user will wonder "just how complicated is this thing?"

How about: "Press Enter to create your new Item. (It may be necessary to press it twice, depending on where you clicked.)"

I'll incorporate the Column wording for fields. How about we hold off the matter of keyboard and menu alternatives until the second or third grid. Best to get the user doing something concrete, and moving forward. Minimalism is an urgent guiding principle, showing "a" way rather than the various ways, so the user doesn't have to read too much before taking an active step.

Thanks for the feedback!

Jerome

(Reduced participation through Saturday.)

Jerome :

I forgot about the option under grids (tools>options>grids....). Thanks!

"Press Enter to create your new Item. (It may be necessary to press it twice, depending on where you clicked.)" is perfect IMO.

Yes, you're right, we can hold off the matter of precise keyboard an menu alternatives. I agree with what you said... you're doing a great job.

Excellent! I took the liberty of copying this to a book page, since it appears we can't markup the text you wrote. See -- link to nonexistent node ID 1007 --

I also quickly threw in 2 comments from A Blank Database., that may help. I liked Calvin's remarks, and had started making up a file per his remarks; however, I think I like the idea of marking of what you've started here,

I thought it would be a good idea to capture comments such as this, since such things tend to get buried deep within the forum, and are nearly impossible to search for, unless you happen to remember the person who wrote it, and a few words...

hmm - should we continue discussion there then ? probably best

Armando - I was checking the instructions in (-- link to nonexistent node ID 860 --) the other day using the new default empty file and clean portable install. I noticed that I needed to click enter twice to create a new item - when in edit mode. Once to get from edit mode to cell selected and another Enter created a new item. I was suprised but I added that to page - but I see this is not the case in most grids in my own file I have here.

I'm not sure what the difference is . . havent had time to look too closely

This setting is Tools>>Options>>1.2.13

>>Excellent! I took the liberty of copying this to a book page, since it appears we can't markup the text you wrote. See 14.50 Tutorial IQbase inwork<<

Hi Keith

That seems like the right choice for markup. But how do we keep book pages from getting cluttered up with comments about transient matters that have long since been resolved? Probably best we continue to discuss in this space, and mark up in that one, unless we have a system for clearing, yet preserving, book-related threads. As this dilemma will recur, what is the Forum's best theory and practice?

Rgds

Jerome

[quote=JJSlote]

>>Excellent! I took the liberty of copying this to a book page, since it appears we can't markup the text you wrote. See 14.50 Tutorial IQbase inwork<<

Hi Keith

Rgds

Jerome

[/quote]

I suggest major discussions in the forum thread, and minor questions/discussions on the book page. That has seemed to work pretty well in the user manual development so far.

Minor things could be put in the "comments" column I added to the book page.

By the way Tom and I experimented with real-time collaboration on the user manual in the google spreadsheets, and it can be handy if schedules/time zones permit. .

Keith

[quote=KeithB]

I suggest major discussions in the forum thread, and minor questions/discussions on the book page. That has seemed to work pretty well in the user manual development so far.

Minor things could be put in the "comments" column I added to the book page.

By the way Tom and I experimented with real-time collaboration on the user manual in the google spreadsheets, and it can be handy if schedules/time zones permit. .

[/quote]

by the book page Keith, do you mean the Manual or the Google spreadsheet ? ( spreadsheets.google.com/ccc )

When you say comments column I presume you mean the spreasdsheet . .

Sorry it wasn't clear, I mean the manual page in both cases--see -- link to nonexistent node ID 1007 --, which I put a couple of comments in.

Do we want to introduce the html pane in the Welcome grid, or wait til a succeeding grid? I'm leaning towards not utilizing it this early.

[quote=KeithB]

Do we want to introduce the html pane in the Welcome grid, or wait til a succeeding grid? I'm leaning towards not utilizing it this early.

[/quote]

I was intending to introduce it in the second grid, which is about all those fields you don't see in columns, and why all items don't appear in all grids. In other words, about populating the grid. The exercise, tentatively, is for the user to get that shopping list from the first grid to appear in the second. Larger objective is to keep building on the shopping list across the entire tutorial, so that when the user is done, he's planned an entire opera in InfoQube, from the soloists, to the ticketing, to the catering, to the sets, down to the embroidery stitching on the costumes.

Well, perhaps that's a bit much for a new user, but we know IQ can handle it. :-)

Jerome

Sounds very good Jerome -

re this first Tutorial page -

I'm still unclear where to edit it ? - I made & proposed a bunch of changes in the Google Spreadsheet - spreadsheets.google.com/ccc

maybe someone (or everyone!) have a glance through them (all changes etc are referenced & signed in comments) and let me know what you think (most are minor or expanding stuff)

I had the idea each person use a different colour text but I dont know if that's just complicating things - helpful if you just adding stuff - that only works in the manual page - unfortunately doesnt work in google spreadsheets (that I know of anyways)

Tom

>>I'm still unclear where to edit it ? - I made & proposed a bunch of changes in the Google Spreadsheet <<

Hi Tom

Keith set up an editable page within the manual, at:

http://www.sqlnotes.net/drupal5/index.php?q=node/1007

The Google spread is useful as a real-time discussion environment, where a group of IQ developer/enthusiasts can get together at a set time. Marking up and commenting within the forum system is asynchronous, and also invites greater feedback from the new and/or nontechnical users we're really creating the tutorial for: Chris, Calvin, Jay, Jan (sometimes) and next year thousands of others.

Absent a more compelling rationale, I vote we continue updates/markup in the manual page linked above, and discussion here. If a group confers via the spreadsheet as well, that'll be quite helpful...but hopefully any consensus that emerges from the spreadsheet discussions can be reported back to the Forum for more general and non-expert feedback on the way to inclusion in the DB.

Rgds

Jerome

[quote=JJSlote]

>>I'm still unclear where to edit it ? - I made & proposed a bunch of changes in the Google Spreadsheet <<

...

Rgds

Jerome

[/quote]

I agree the -- link to nonexistent node ID 1007 -- should be our master working document.

Tom, I'm finding the editing environment of the spreadsheet a good working tool; I suggest if one of us have a major edit, we might ask Jerome's opinion via the spreadsheet and a private email, if we don't want everyone's opinion just quite yet. That could be useful, even if not quite real-time.

Jerome, thanks for "running" with this tutorial idea. As was the manual and examples, this has been talked about for a long time, and it's great to see something coming together.

[quote=JJSlote]

>>I'm still unclear where to edit it ? - I made & proposed a bunch of changes in the Google Spreadsheet <

...

okay I'll add those changes to the manual page, you can revert or change as you wish - please have a quick look (spreadsheet) though cause some are ideas I threw out there & am not 100% sure of myself - if you request I will use a different colour for my edit of the book (manual) page, otherwise you can look at the revisions page for details -

oh....I see we seem to have lost the ability to compare revisions in the manual pages - or is that just me?

>I see we seem to have lost the ability to compare revisions in the manual pages - or is that just me?

It has been a few months now that this feature is not working. IIRC, I was changed server and I need to ask them to install some extra stuff. I'll look into this this week.

Tom, I appreciate your trying to cover every base. And I hate to be a stick in the mud. But I do plan to revert most of those changes. They're dull writing, and technically wrong for Grid1.

For example: I've started the user off in mainly keyboard mode just so we don't have to add a parenthetical like "(and allows you to select the full row/item)" and the redundant sentence: "Select the item by clicking in the # column on the left and then experiment using the Alt and various Arrow keys to move the item." Alt-Arrow keys work just as well in edit mode as in item select mode, and just as well in the Item column as in the # column. The user will be wrestling with item vs. field selection soon enough.

And for the sake of pacing, and because it's a hands-on tutorial, we can invite the user to see what Ctrl-1 and Ctrl-2 do; we don't have to spell it out for him with IQ jargon and parentheticals. If we say "to break long text sequences like this one into multiple lines or paragraphs," we don't also have to say "While you are editing/adding text to an Item."

The user's patience and attention are at a premium. The manual can be comprehensive; but in a tutorial we pare down, give the user one route, and keep it lively. It's just a different tool and style for a different purpose. Thanks for understanding. I expect to be borrowing from your manual pages, and am also hoping you can be primary author of one or more subsequent tutorial grids.

Cheers

Jerome

"Pacing" --great comment. I had a few quick thoughts:

1) Shopping list does exist in the sample database--"oh no, not another shopping list", the prospective new user says after looking at the sample database. However Calvin's "note pad" might be a little too generic... Maybe an "errand list"?

2) I pulled the present text into an iqbase, to assess it visually--#1-3 look about right, #4 is visual overload. I think anything that size would need to be split into two items, even if there is only one main thought.

3) It can be human nature to want to skip the examples at least at first. I propose the second grid be titled "outliner" and start with "Here's the shopping list (or errand list etc) you entered in the Welcome grid... and list 4-5 items they "entered" then introduce one or two enhancements--maybe the html pane and/or adding another column to the grid.

[quote=KeithB]

[/quote]

1) shopping list I find good (still)

2) item 4 has five separate points - would you consider making these sub-items or do you want to avoid that?

3) the reason I wanted an item with sub+sub items in the grid is that I ~~suspect~~ know some people will start trying things out (specifically Ctrl+1 etc) before or without actually creating the list.

Keith are you saying if they dont make the shopping list they will be sent back from Grid #2 ? (nice idea I think!)

Hi Tom,

Oops, at first, I thought these comments were Jerome's!

After looking at the database some more, I changed my mind on #1 & #2, they're okay.

As to the second grid, I thought the tutor should be a lenient teacher, and have something like this:

I attached my file.

Jerome, I think I reverted back to where you were indicating. I worked through the Welcome prior to creating my partial grid 2 concept, and I would have been "stuck" had I not known about the dreaded "refresh".

Okay Jerome, points taken.

I'm learning myself here - I never knew that the Alt+Arrow keys also worked in edit mode!
-
"and allows you to select the full row/item" will have to be added at some stage (when they need to select item - as you say this not yet here) - I found item selection problematic in IQ initially (early on I started hiding the # column to make space) so I suspect some other beginners might also.

With the Ctrl+J - I suspect some people will be, like me attempting this while not in edit mode and thinking Huh? nothing happening here so (the previous instructions were for while not in edit mode - you may think it unlikely that someone tries this, that but you can also be sure that I wont be the only one). I know (?) there is the ability to split items - maybe that's what had me trying it while not in edit mode. I would like that sentence to be made a little clearer, maybe rewritten.

Actually we'll have to get Calvin to have a look at it - sometimes a little knowledge is a dangerous thing (I mean mine) - I can see now I was approaching this with my own sometimes incorrect ideas or without full understanding but also trying to make clearer the things that I found confusing at one stage or another

I see you're an optimist Jerome ("Thanks for understanding.") - it is challenging when someone calls your writing dull but I also think directness is good :-)

-- link to nonexistent node ID 1007 --

I tried to revert page back to a previous version before my edits but it doesn't seem possible, so I undid all but one edit and left two 'proposals' in the comments.

If no-one objects I would like to also remove the work I did on the Work-done grid - that was done a long time ago, is partly out of date - and it's content & style etc. will very much depend on what is covered in previous tutorial grids (I can link to where it is in the forum)

[quote=Tom]

-- link to nonexistent node ID 1007 --

[/quote]

Tom, go ahead and remove it. I put that and Calvin's post there to help me think through stuff. As I've mentioned before, there is so much in this forum, it's too much to keep track of. (At least until I get disciplined enough to use IQ to document specific comments...)

The inline tutorial is wide open for participation and leadership. I'm using IQ -- actually about 5% of IQ's capabilities -- with great pleasure and benefit, but am not finding space for significant Forum activities at the moment.

A salute to the core group that is plumbing IQ with endless enthusiasm at such a rich level of detail.

Cheers

Jerome

edit/

first many thanks for your help so far Jerome!

/edit

[quote=JJSlote]

[...] am not finding space for significant Forum activities at the moment.[/quote]

that's a pity Jerome, especially in the context of this thread - you have such a clear view about what is necessary for the tutorial ...

Thanks for your participation and note Jerome. Hopefully, you'll find some time soon -- your presence here is greatly appreciated.

Thank you for getting the ball rolling. I'll try to keep it going.

I am presently experimenting working directly with the .sndb file on the manual page, and updated Grid2, and started up grid3. My creative juices seem to flow better when working directly with IQ.

I've been making modifications to tutorial03.sndb, then saving it as tutorial04.sndb, etc. Anyone that can free up some time is welcome to roll up their sleeves and help.