Explanans

The domain registration bug just bit, and I registered explanans.com, org, net.

http://www.iscid.org/encyclopedia/Explanans http://www.iscid.org/encyclopedia/Explanandum

The explanans is the thing or solution that explains a problem.

The explanandum is the thing or problem that needs to be explained.

Consider the following sentence: The man died because he was shot. In this sentence, the explanans can be identified as "he was shot." "He was shot" is the reason that "the man died.", the explanandum is "the man died."

=======================================

I would prefer an example more like "The man had compassion because he rejected fear" ... no matter.

=======================================

I have found my documentation obsession preferring the term 'explanation' over 'documentation'. The realms I draw upon, the book 'Single Sourcing' by Kurt Ament, and the Zope3 component architecture both focus on the assembly of 'chunks', 'components'. Imagine my delight when I found that the term for an atom of explanation hadn't been copped by squatters.

So it's me what cops the squat. WooHoo.

Dependencies question

I want to check out Inkscape's `import from openclipart.org` capability.

A bit of searching reveals the requirement for gnome-vfs

$ apt-cache search gnome-vfs

This returns a long list, I guess at

$ sudo apt-get install libgnome-vfs-dev

guessing correctly that the dev package will bring in libgnome-vfs-common

$ ./configure | less

dang, `Use gnome-vfs: no

I need to install more packages. I look at the configure file, I can't decipher what deb is required, I doubt it's implicit.

So, as many times in the past, I install likely looking packages until I get in ./configure::

Use gnome-vfs: yes

It turned out to require::

$ sudo apt-get install libgnome-vfsmm-2.6-dev

I would like to document this, but at this point I'm not sure whether

$ sudo apt-get install libgnome-vfs-dev libgnome-vfsmm-2.6-dev

is adequate, or if another package I guessed at was required. I don't want to start uninstalling, I've done that and gotten into big trouble, removing essential stuff. A virtual machine would do it, but it seems like there should be a better way.

Getting indignant

My obsession with documentation has started to take a somewhat
unsettling turn. It is making me ignorant. Let me explain.

Almost all of my reading is non-fiction at best, tends to be
technical. Lately, as I read, from deep inside I hear a voice saying::

"I refuse to understand this. What the author is describing
would be explained at a glance with the proper diagram. Since
there's no diagram, I'll cover my ears and chant 'la la la'
loudly. So there"

Case in point; the instructions for taking care of the hole in my jaw left by my recent tooth extractions. The handout described what to do and for how long, covering about 10 days. Where's the timeline? As I read I have to mentally create an image of taking ibuprofen, rinsing with salt and baking soda, not eating nuts, flushing with the little syringe thingy ... then visualize the next 10 days, associating each event with a range of days. Come on! If *you* took the effort to make that timeline, all the readers of the pamphlet would be spared.

Some things, like Zope's component architecture are even more
complicated than care of ex-teeth, don't get me started.

Nothing however, is more inscrutable than the workings of our pressure tank. Because it's filled by an old jack pump, it must be bladderless. A float-operated, adjustable air valve controls when air is released from the tank. It defies *all* comprehension.

Documentation theory

The following is taken from an email to a friend. It is an attempt to describe a theory of documentation I am obsessed with. Of the people I've told this to, I've gotten reactions ranging from 'it won't work', to 'it's not necessary', to embarassed silence, to 'do you want to go for a bike ride?'*

======================================================

I learn things slowly, you learn things quickly. I am coming to believe that explanations could be offered to me (and those like me) which would lead to understanding more efficiently than what is currently available.

When you are thinking about a question or problem, you close your eyes. My guess is that you are doing a transformation to a visual version of the problem domain. The math savant describes his recitation of PI as traveling through a land of numbers, he LOOKS at them.

The traditional linear narrative explanation of concepts assumes that the reader is, in real time, creating the images required to grok the meanings and relationships of the words.

I don't do that, it takes MUCH repetition before the understanding produces an image of the domain. I suspect that others have a similar cognitive process. I guess that involves the visual vs oral learning style stuff I've read about - "I see what you mean"

I see stuff that's already there, I'm not good at creating it in my head from descriptions. You are.

I think the words can be taken from the symbolic realm of the linear narrative and located in space, on a page.

An example would be producing a printed page which explained how a method call worked. On the page would be the pertinent parameter definitions, the lines which called subroutines, the lines which returned values etc. The connectors between the text pullouts would be annotated. The pullouts from the pertinent config files would be on the page.

The text is an image of words, arranged in a way which reflects the symbolic usage of them. A nudge in the direction of what I think is required to understand at a level to make use of the concepts.

I think it applies to lots of things, and has a simple basis, and can be codified: I want Python code to convert text files to SVG elements. The text becomes graphic, you can shrink, color, pull quote, change it's opacity, rotate it, and POSITION IT. My theory is that you (and folks like you) are able to _position_ concepts in order to understand them. And the framework easily accommodates standard images as well as images of words.

And of course, this is all automatable, once the tools are in place, the computer is taught how to do the pulling and arranging of the constituents of a concept.

This is something I'd love to talk about with you.


* joke reference::

Q How many ADD kids does it take to change a lightbulb?

A Do you want to go for a bike ride?

doctest from Vim

I want to become comfortable with the Vim way of editing, I'm convinced it will save me much time, since I seem to be on a path which involves lots of keyboarding.

A new member of the zcadoc project recently pointed out that Baiju's choice for an example application has the potential to be confusing. It's a hotel app, which handles guest registrations. The ZCA involves registering components, so the word is used in 2 ways.

Maybe we can change the spelling of a couple terms to avoid the confusion.

So.

izca.txt holds the book in ReStructured text, with the examples in doctest format.

I need to do text replacements, running doctest on the results to see what broke. This seems like a common enough use case to take the time to study how to do it efficiently. I can picture a Vim expert making the changes, running the tests, tweaking the changes ... all from the keyboard, using few keystrokes.

All that's required to run the doctests in the book is::

import doctest; doctest.testfile('izca.txt')

I made a file ``dtbook`` in the book directory::

#!/usr/bin/python
import doctest
doctest.docfile('izca.txt')

now, if I enter the following while in Vim normal mode::

:r! ./dtbook

The file tests run, and any tracebacks are pasted into the file.
I can do {lineno}G to jump to each problem line, delete the tracebacks
when finished.

Next, start renaming.

The first time

In the spirit of 'docubi' my branding for Documentation that is Ubiquitous, I created a gmail account, docubi, where I will send things I want to be remembered / documented.

- urls
- notes
- emails
- command results

It was the last which gave me a spooky experience, success without the obligatory failures / debugging.

Vim is pretty Ubiquitous, a Windows install offers 'Edit with Vim' from an explorer rclick, fine on Linux. I like the Vim feature
:r!
which runs a command and places the output in the file.

So.

If I do an install, configure or some such from Vim, saving the output, I want to send that file to the docubi mail account for later processing. And I want the lowest possible denominator for the tools to do it.

Starting with Windows, which I expect to be problematic, some options.

- a Vim script
- I don't want to learn Vim scripting

- a Python via
:py mailThisFile.py
- requires Python, not available on Windows machines, I'm ok with adding my c:\bin dir and installing Vim, but I'd prefer not to install Python on every machine I sit down at.

- A native binary and a batch file

A search turned up
http://www.beyondlogic.org/solutions/cmdlinemail/cmdlinemail.htm

`BeyondLogic` sounds familiar, I think I've been led there before.

Here's the scary part. I downloaded and put in c:\bin bmail.exe, a 44k file. I then typed::

C:> bmail -s {my smtp server} -t {the docubi address at gmail} - f {a return address} -a testing bmail -d


And it worked. First time. Not that it shouldn't, but IT NEVER DOES.

Hello? ... Errors? ... Where are you?

The only explanation I can think of is that, because the workstation I just migrated to seems to have irrecoverably scrambled it's registry upon my plugging in a USB stick, I've somehow earned a glimpse into a parallel universe.

Exposure

Last night, in the sauna, I realized the code fragment in the last post is dead wrong, a good demonstration of how far I am from grasping ZCA.

My initial feeling of embarrassment passed, and was replaced by interest in how and why I am so wrong in my understanding. I need to overcome my resistance to exposing ignorance if I'm going to hang in this blogosphere place.

====

I instantiated an interface. Discussions of interfaces tend to start with the fact that you do not instantiate interfaces. Why has that never sunk in?

My understanding of object oriented programming has class definition at the top, an object is created from the class, the object does things. Since ZCA explanations start with Interfaces, in my mind I associated them with classes.

It's as though there's a tree with many bird nests in it. There's a nest for classes, methods, attributes, functions etc. When *reading* about Interfaces they just roost on any available branch. *Writing* about them requires putting them in a nest. Since there isn't a nest for them, they ended up with classes.

I kind of like that analogy. I realize it's pretty basic stuff, we have notions which we try to understand the world with.

I like it because of the similarity to one of my favorite analogies. In a class on Native American languages I read a description of a Native American understanding of time. The writer described being in a bubble of the *manifest*, floating in a sea of the *unmanifest*. The bubble is generally considered "here and now". There are ways to access that which is outside the bubble. This in stark contrast to the European concept of time consisting of a journey along a line, with the future ahead, the past behind.

I am finding it useful to consider my little mind a bubble of things known floating in a sea of things unknown. This lines up nicely with ADD issues. I know with great certainty that my learning is not linear, but consists of struggling to pull items into my bubble.

When I come to understand something it has a nest in the tree. In the case of Interfaces, I need to understand that the existing nests don't meet the needs at hand.

I've heard that people learn object oriented programming more quickly if they haven't already learned procedural. I wonder if it would be easier to learn component based programming without a background in objects.

Future photos

I do a lot of digital photography, and as a student of programming, I have lots of ideas about software which would be useful for dealing with my photos.

I am currently studying zope component architecture via some editing of Baiju's book, I would like to begin a project applying ZCA to a real issue.

So, given ShotInFuture.jpg an image with a bad date::

>>> import ZCAImageTool
>>> batch = ZCAImageTool(storage=memory)
>>> imref = batch.add('ShotInTheFuture.jpg')
>>> print imref.filedate(year), ' ', imref.exifdate(year)
2008 2008

>>> imref.filedate(year) = imref.exifdate(year) = 2007
>>> print imref.filedate(year), ' ', imref.exifdate(year)
2007 2007

I really want to change all the files::

>>> batch.clear()
>>> batch.add('/home/ktenney/photos/nextyear')
>>> batch.filedate(year) = batch.exifdate(year) = 2007
>>> print batch.filedate(year)
2007

batch.filedate(year) would have some smarts::

>>> batch.filedate['bad.jpg'] = 2008
>>> print batch.filedate(year)
Mixed batch.
bad.jpg = 2008, others = 2007

I would like to lure Baiju and anyone else that might be interested, into helping put code behind these tests. The process would involve, among other things;

- deciding what existing interface to extend
- designing the interface
- writing the date/EXIF code in a ZCA-agnostic style
- registering the components
- ...

Background item #1
==============

My wonderful old Nikon Coolpix 990 has a dead memory battery, so every time I change the AA batteries I need to reset the date and a few other things. I tend to hurry through the setting process.

It turns out the latest batch of photos I've shot were shot in 2008. The photos are landscapes and such, no stock reports or newspapers, so I have nothing to gain by this glimpse into the future. It will, however, foul up photo managing software, where linear time is assumed.

So, I want to reset the year on the files, both on the file and in EXIF.

Background item #2
==============

A few years back I read some posts about a project that a C++ coder was doing, a tutorial based on email exchanges with a student learning C++ from scratch. I only followed it briefly, but I really liked what I read, and have continued to consider it a really effective approach, a revealling examination of the learning process.

zcadoc at Launchpad

Baiju's book is now available in a branch of the Launchpad zcadoc project

There's also a zcadoc team. I don't yet understand just how these elements work together.

I did a bit of branding for each.

The photo for zcadoc is one of my favorites, at least one friend saw it the way I intended; I walked the field collecting as many different seed heads as I could find, the photo means to explain *these are the grasses in this field*


For some reason I have this belief that there is considerable untapped potential in using images for explanations.

I'm not sure how well the large one for the team works, it is a photo of a team in action. Again the field, this time Kathy, Scott and Shunka the dog working together to roll a hay bale.



The 64 and 14 pixel images are of keyboard keys spelling out zcadoc crossword style. I have high hopes for it, it has lots of potential for monkeying with a larger version; embedding images into the blank keys etc. I also thought it might scale down to 14x14, staying recognizable due to the simple geometry and color.



Again *We'll See*

Global collaboration

I gave the URL of this blog to a new friend, I might get a visitor!

... gotta tidy up, sweep the stairs, check the buckets* (we don't get too many folks coming 'round these parts)

I'm quite excited about the circumstances which might bring Baiju here.
(see "For surely there is an end ..." in "Recommended")

I've been wanting to learn how to use Zope 3, and Baiju is a Z3 developer who wrote an Z3 article which is becoming a book. I am doing a bit of editing for Baiju. My daughter is in school, and is teaching me the advantage of taking notes while reading, marking up the book. I am very grateful for the opportunity for my studying / note taking to benefit someone else.

Baiju's deep understanding of a powerful tool is something I want.

The fact that I've lived my life in an English speaking country gives me something to offer Baiju.

Cool.

Thanks,
Kent

* more on the buckets later

So much to do

Howdy,

All my life I wanted a nickname, I finally got one from my
grandson. I now proudly answer to Gumpa.

My pursuits straddle many domains, which I hope to
chronicle here, at omh.

Currently::

- Zope3
- Leo
- SVG
- Vim
- Theory of, and creation of, documentation
- ReST
- Plone
- System administration
- Image management
- Too many political/economic topics to list here

You can't spell straddle without ADD

So, what else? add blogging to the list.
I do hope that this can provide a degree of accountability,
an opportunity to step back and help me focus.

We'll see.

Thanks,
Kent