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.
2007-12-30
2007-12-23
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.
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.
2007-12-20
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.
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.
2007-12-06
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?
======================================================
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?
Subscribe to:
Posts (Atom)
