FAFO 8

FAFO on GitHub

A little planning on what I might like to do. No code, just thoughts. Wow, “slug” has a lot of meanings.

(Actually started Friday afternoon)

I’m imagining a text file (document). It has some text in it, some links (ala hyperlinks) to other text documents, and it has some inclusions in it, links to other documents which are to be included directly in the displayed text.

t1:
blah blah blah
mumble
<link t3>
argle bargle
<include t2>
thrilling conclusion

t2:
tra la la
vo do oh doh

t3:

Those files might produce a display like:

blah blah blah

mumble

(see also t3)

argle bargle

coherent thought

thrilling conclusion

(Now Saturday morning 0815)

My brother from another … maybe planet? — GeePaw Hill has buckled down and is getting started on the real product idea, as reported here.

Let the wild rumpus start!

As per yesterday, I’ve set up a new public repo for “currytree”, a small-scale system for the management and presentation of dynamic material for a curriculum.

This presents me with a problem. As he shapes his idea, it makes me think that my weird angles are of limited value to his app. Which is odd, because I never really thought that what I was doing was applicable to his app: they’re just ideas about how I might build such a thing if I were to build it. And I had in mind using ideas in my experiment that I would probably never really use in the real thing … like set theory.

I think I’ll just go ahead with whatever comes to mind … and I strongly urge you to follow GeePaw. If you do, I think you’ll see some very interesting and useful things.

And I’ll try to do some things here that are interesting, if not useful. We’ll see.

The product idea

Do read GeePaw’s toots, as they’ll be a more coherent description of what needs to be done than I will have, and keep in mind that I will surely have a different product in mind as well as a different way of building such a thing.

By my lights, we’re looking at a curriculum, created by “authors” consisting of a lot of documents, from which a series is selected by “guides”, for a “cohort” of “students” to work through as part of their education.

The documents will be “tree-like”, in that a given document may have subordinate sub-documents. In Hill’s model, every document has “text”, and some have subordinate documents. He is thinking of an app with a tree-browser style, with a tree window showing the structure, and various other widgetry as needed. So far, in his model, I guess you cursor or click down the tree as you read.

As an author, I think of my document as tree-like, but not with all the sub-documents at the end of their parent, but showing up as the parent goes along, perhaps an introductory paragraph, then a child with details about that, then some more explanation, then another details child, and so on.

While I might contemplate that a student reader might skip over some bits, I would be thinking mostly in terms of a linear flow such as you’d typically see in a book, introductory paragraph with details next, then some explanation, then some more details. So I would perhaps write in tree form, but I expect the reader to see a flat form.

In other situations, things might be separated, rather than in line. Footnotes would be an example of that. You might see the footnote indicator¹ but would have to click it or something to see the footnote.

Associated with parts of the overall document, we would have exercises. It seems likely that the authors and guides would create many exercises, and that each cohort might be given a different set of exercises, to keep things fresh and to deal with the very real possibility of students building a database of exercise solutions. (I know that Hill is not concerned about students cheating: they are cheating only themselves after all. But in any case it seems we’ll be likely to want different exercises for different cohorts. Perhaps even on a per student basis?)

So as an author, I might have a marker or a sub-document for exercises, but it might not even be filled in with actual exercises in the main chunk of course-ware that I create. They might be left for later.

Now as a guide, my job is to produce, for my cohort, a “linear” flow through a selected set of documents. I’ll select from many authors, and I’ll choose the series of documents that the students will see. Ideally, I suppose we’d prefer to select a whole document or not select it, but it seems very likely that, instead, we’ll find that chapter seven of Joe’s document is just too hard for this group, and we want instead to include chapter nine of Alice’s document. So the guide is kind of cutting and pasting available documents to create a path for their cohort.

The guide will also collect or create assignment documents, and interleave those as necessary.

The result of the guide’s work, as I envision it, is a series of documents, some of them with child documents just as before, but that the series is an ordered selection of documents from the entire document collection of the curriculum enterprise.

The student, who both by count and by focus, is the primary user of the product, is presented with a document tree through which they work. And … associated with that tree, there are actions, triggers, switches, gates, I don’t know what, that control the student’s flow through the tree. Most simply: parts of the tree will not appear until the student has completed some task in the visible part². Other actions might trigger a message to the guide to examine the student’s answer to some question in the text. And so on. We do not know what the actions will be, we’re just sure that there will be some.

Some Ron thoughts

• I am not terribly interested in building a lovely GUI for this app. In fact I am almost terribly uninterested in doing that, as I don’t know how to build windows with Python and from my reading of what’s available, I mostly do not want to.

• I absolutely do not want to work with “Rich Text”. I might go so far as to demonstrate documents written in Markdown rendered to HTML in a web browser. Not that that’s a great accomplishment, but it would demonstrate nearly end-to-end behavior. At this writing, I believe that Python does not have a convenient web browser object for use in native GUIs. I don’t blame them. It would probably be easier to build the whole app to run in a browser.

• I happen to know that Hill tends to vomit when you talk about apps running in browsers. I commiserate, but may choose this pragmatic approach anyway, as I am not really here to build the product.

• This app runs quite close to the setup I have for creating my web site. Jekyll builds my entire web site from a tree of Markdown and other files, creating a tree of HTML and other files, which I FTP to my ISP for your delectation. The FTP tool is clever enough not to send unchanged files, which is a good thing, since there are over 5600 files on the site. (Wow.) It is tempting to think of building my own private Jekyll-like thing for better control over my web site. I hope this idea does not take hold.

• It seems clear that each document should be stored in a simple key-value form, with the key being some somewhat human readable identifier for the document and the value being the document. A document with children would identify them by their keys. Hill refers to this key as a “slug”, by which I assume he does not mean those homeless snails one finds around the garden. Nor, I suppose, does he mean a sudden blow to the head or a large swallow of Die Coke, nor a bullet from his trusty six-shooter. Who knew that “slug” had so many meanings?

• Perhaps that means that a path? created by a guide will essentially consist of a list of slugs³. But from the guide’s viewpoint? They’ll want to be doing something like selecting from the big tree or trees of authored material, moving sub-trees to their path and munging them around. Having tried to do that with both Scrivener and some other far more horrible book designing program, PageMaker or something, I think that is a difficult human factors problem. I am hopeful that the underlying information structure problems will be far more simple: basically just a list of slugs.

• In my view there will be links to separate documents and inclusions of separate documents in line. Let’s imagine such a structure, and two views of it. The text view will consist of the text of the top document with the interleaved text of included documents, containing links to other documents, all the way down, in a big long book type thing. The tree view will look like an outline, starting with the slug (or title?) of the top document, with its linked documents shown as subordinates, in the standard outline way.

• What about actions, triggers, and such? I don’t know. I suppose that some triggers will fire when a document is opened. Some may actually be triggered by the user: check this box when you have completed the exercise, or press this save button to save your proposed solution. Some may trigger when a document is left, as you go to the next one. We’ll just make some up, I guess, unless Hill publishes more ideas.

Design? So far …

Documents with slugs, containing other slugs. Lists and trees of slugs. There’s hardly any mechanism there.

I know one and a half ways to deal with trees of things. There is the famous Gang of Four pattern: Composite, which is just exactly custom made for such things. And I can almost envision a set-theoretic way of doing a very similar thing.

First cut, some text and slugs:

< text1, sluga, text2, slugb, text3 >

Second cut, the bits identified as to type:

< <"t", text1>, <"s", sluga>, <"t", text2>, <"s", slugb>, <"t", text3> >

Third cut, explicit scopes for outer ordered collection:

{ <"t", text1>@0, <"s", sluga>@1, <"t",text2>@2, <"s", slugb@3, <"t", text3>@4}

Pay little attention to the notation, I’ll explain it if we ever use it in anger.

So an ordered collection of objects. I am not seeing much value to set theory here. Just some kind of “smart” document that can contain text and slugs, and probably identify whether they are include type or link type.

Huh …

If we have a smart document like that, we can finesse the GoF Composite or deep set trees⁴. We can, I think, clearly display the text with hyperlinks, and we can “obviouslY” construct a display tree if we need one.

There’s our spike!

I think what I’ll do is a textish file with regular text and embedded slugs, identified as link or include type, and demonstrate that I can render the inclusions and produce a suitable tree. Or maybe an object with a list?

I’ll do some code next time. This time, just thoughts.

See you next time, I hope!