InfoQube IM - Community

Submitted by KeithB on 2009/06/03 22:32

I need some help/opinions on the manual, reference 2. Edit Menu.

1) What is auto-edit? I didn't find any direct definitions in any of the old documentation, and I couldn't find it in the ecco manual.

2) I started throwing in stuff in 2. Edit Menu. Now I'm thinking ahead, how to integrate all this stuff (or whether to worry about it at this time).

For the comment field, do I copy the explanatory text over from the keyboard shortcut sections, do I hyperlink to that section, do I write a synopsis with a link, or do I paraphrase? (Or all the above?). The same question as to the toolbars pages, and the community glossary pages!

3) I added the reference field, which IMHO should help keep track of things. I put the present manual section number, etc. I'm undecided whether to put hyperlinks in there now.

4) Are there any comments out there, as to where the manual is ultimately headed? I ask this, in having used a bazillion programs at home and at work, have yet to find a manual I really liked that well. Will it ultimately end up being an iqbase, like the sample? Quick start guide? Full manual no one ever reads?

Anyone out there have any documentation from other programs that you think is exemplary??? (I did look at the old ecco manual, and it did seem excellent).

Comments

I don't know if this is happening already -- or if not -- if it's possible -- but I would make the manual an IQ topic. There's nothing easier / faster or more common than <CTRL>+F & it won't take up that much room.

Jan Rifkinson

Ridgefield CT USA

HP Blackbird Vista Ultimate SP-1

Auto-edit. In Auto-edit, you can't really surf on your items, cursor movements automatically trigger an edit. I never use it. Ecco was always in auto-edit, so it is there for ex-Ecco users
I wouldn't worry too much about the final form of the doc. I think, many commands are self-explanatory. Those that are not, best is if you put in your own words what it does. It is likely to be less technical than what I could come up with
Putting a hyperlink would be nice, using the [node] syntax described in Linking to other pages is easy and will automatically update if page title changes
That's a hard one, but I "think" that most of the work will be done here, exported to an IQBase and then to CHM for final linking with IQ (i.e. F1 help)

(BTW, did you notice the new Export links in the book pages. This will allow easy export to IQ. Also, an IQBase to CHM export is planned)
And yes, the Ecco manual/on-line help was excellent

This will be little more than a quick comment, and not in itself all that helpful... I'm not in a position yet to be able to answer my own questions! And maybe others can give those answers.

I am really studying the IQ documentation now, in an effort to understand the full potential of the program (which I'm convinced can be great). I'm one of those silly people who tries to understand things before I do them - as a consequence, I took about forty years to learn to swim!

I have two overall reactions, so far, to the documentation:

The documentation is, in common with most software documentation, a description of what the software does. That makes for useful reference material but does not help people to learn how to use it in order to do something useful. There's a legal excuse for this approach, at least in the United Kingdom where I come from originally, which is that if a company describes how to do something useful, it is also potentially legally liable for an implicit "fitness for purpose" for what it claims to be able to do. Companies often avoided that by simply describing the functionality of the software, leaving it up to the reader to figure out how that functionality might actually help them to get things done.
A more subtle point but one which I personally think is crucial. One of the major reasons why people can't or won't use a program to its full potential (or at all) is if their mental model of what the program or system does is wrong or incomplete, that is their mental model is not coherent with what the system actually is and does. Now IQ (as Ecco before it) is built on a very powerful information model which is very difficult to explain or teach. Now the very first page of the manual does what kindergarten teachers do, which is to simplify things in order to avoid confusion. In my opinion it achieves the opposite effect. As a simple example, it starts off talking about sheets and not grids. Granted grids are not easy to grasp at first sight: but grids are the primary view of information provided by IQ and one shouldn't start off by avoiding that. (Small aside: I don't like the word grid too much either; a grid is, I think, a view, but not the only one; the calendar can be described as a grid but it's a lot more than that. Grid is a good word for starters, but it won't cut it when we get mindmaps as a way of inputting and structuring information!)

I believe that I basically mastered Ecco, eventually. And its manual was and is a work of excellence. But it too ducked the really difficult questions, which are "what is Ecco " (or IQ) "and how does it structure data?" Ecco also tried to seduce people into buying it by emphasising important but partial views - calendar, contacts, to-dos, which are the reasons why people usually buy PIMs. As a consequence I am still, fifteen years later unable fully to articulate what Ecco does and why it's so good at it. So, Pierre: you have an internal data structure or model in IQ which is very powerful because it is- to use the jargon - canonical.

Wikipedia descibes "canonical" as:

Some circles in the field of computer science have borrowed this usage from mathematicians. It has come to mean "the usual or standard state or manner of something"; for example, "the canonical way to organize a file system is as a hierarchy, with extensions to make it a directed graph".^[4]XML Signature defines canonicalization as the process of converting XML content to a canonical form, to take into account changes that can invalidate a signature over that data (from JWSDP 1.6).

In enterprise application integration, the "canonical data model" is a design pattern used to communicate between different data formats. It introduces an additional format, called the "canonical format", "canonical document type" or "canonical data model".

I think that you should be bold, come clean on what the IQ canonical data model is and explain it, its advantages and why you've adopted it. I guess that may risk your intellectual property; and to do it well may mean that you have to explain it first to KeithB or others so that they can take a journalistic or technical author's point-of-view and present it better. But somewhere - not in the Introduction or Getting Started bit, but somewhere early - we need to be told what IQ really is and maybe even how then to begin to exploit it fully!

If all this sounds horribly theoretical - it certainly isn't. Finding answers to very simple questions, like how to link information between grids or to restrict field values to a predefined (validating) list, is just too hard with the documentation written and structured as it is at the moment. I'm not going to give up, but I suspect that many people might! And no, it's not good enough to depend on this forum to answer difficult questions. I'm sure that I'm not the only person in the world who finds forums and content management systems depressingly difficult when looking for existing answers to questions.

Instead: if you understand something well enough, you can then do things better. That's why doctors and surgeons have to go through years of education. I'm convinced that if I knew a bit more how IQ works, I would be able to use it better.

Mark Gregory, Rennes, France - GMT +1/+2; EST +6

As a pragmatist, I think providing practical examples of how things work is a good learning tool as well .

Jan Rifkinson

Ridgefield CT USA

HP Blackbird Vista Ultimate SP-1

That's some wonderful feedback. I hope you hang in there, and eventually help on the documentation; there are just a handful of us trying to help Pierre out with documentation, and no one with an Ecco background, as far as I know. Maybe it can be made to cover both what the software does, "learn how to use it in order to do something useful".

I have had some frustrations with documentation, and lack thereof, and decided to jump in a few months ago and try to help.

You're right that it's a pain to search through the forum. Or in my case, I search in this forum, and the old forum, and the donationcoder forum; (reference the blogs of those forums I captured).

I'd rather have Pierre do 80/20 programming or better, at least til after 1.0.

"Difficult to explain or teach" is an understatement, but I find that for me, graphics help immensely, supplementing the words.

Now if we could just get someone addicted to writing samples and templates.

Or someone willing to take the time to scrub their main file of PII, and put it in a blog for others to learn from.

Thank you! And thanks a million for doing what you're doing. The documentation is improving all the time. It's a measure of Pierre's achievement that there is so much to describe! I am of course writing down stuff as I go along concerning how to get things done with IQ. I don't yet feel competent to go public on it, but I will.

I have had some frustrations with documentation, and lack thereof, and decided to jump in a few months ago and try to help.

You're right that it's a pain to search through the forum. Or in my case, I search in this forum, and the old forum, and the donationcoder forum; (reference the blogs of those forums I captured).

A lot of what is in the forums would, in an ideal world, migrate into the formal documentation.

I'd rather have Pierre do 80/20 programming or better, at least til after 1.0.

Bravo, I have to agree - but that said, only Pierre can provide the "raw" documentation on which better stuff can then be based.

"Difficult to explain or teach" is an understatement, but I find that for me, graphics help immensely, supplementing the words.

And you've done a wonderful job providing them.

Now if we could just get someone addicted to writing samples and templates. Or someone willing to take the time to scrub their main file of PII, and put it in a blog for others to learn from.

Or in the cloud! I'm doing a part-time Ph.D centreing on personal and small-group information management. If Pierre is up for the challenge, I would love to put my Ph.D plan up as one of a number of publicly-accessible IQbases - but again, I want to improve it a bit so that it's not too embarassing!

Mark Gregory, Rennes, France - GMT +1/+2; EST +6