Discussion on improving documentation

[tfjern]

jjinwi wrote:

"I am continually amazed at what UR can do :-)"

How many times have you found out how to do something useful in UR by "accident" or by scanning the forums? This is a major problem that has been discussed several times before in the forums: namely, UR has an appallingly user-unfriendly help file (albeit very neat and orderly), which seems to be in inverse proportion to the power and usefulness of the program itself. Obviously the help file was created by one or more of the actual programmers, and this is a no-no, as I believe I mentioned in a thread some time ago.

I'm sure all of us who have purchased UR want to see it succeed on the market, so I hope kinook will start thinking about providing user-friendly online videos (the current ones are inadequate) and a thoroughly redesigned help file that can show the average user in detail how to use UR's powerful features, many of which I still haven't figured out -- but thanks to these forums I am "discovering" one by one, but is this the best way to learn about the program?

[quant]

Originally posted by tfjern
jjinwi wrote:

"I am continually amazed at what UR can do :-)"

How many times have you found out how to do something useful in UR by "accident" or by scanning the forums? This is a major problem that has been discussed several times before in the forums: namely, UR has an appallingly user-unfriendly help file (albeit very neat and orderly), which seems to be in inverse proportion to the power and usefulness of the program itself. Obviously the help file was created by one or more of the actual programmers, and this is a no-no, as I believe I mentioned in a thread some time ago.

I'm sure all of us who have purchased UR want to see it succeed on the market, so I hope kinook will start thinking about providing user-friendly online videos (the current ones are inadequate) and a thoroughly redesigned help file that can show the average user in detail how to use UR's powerful features, many of which I still haven't figured out -- but thanks to these forums I am "discovering" one by one, but is this the best way to learn about the program?
people are amazed because they don't read help file (myself included :-) )

My estimate is that 95% or more of questions of users on this forum could be answered just by checking the help file. People are LAZY to look for answer ... it's 100 times easier to spell it on the forum and wait for someone to give you straightforward answer to your exact problem.

UR is very robust program with many functions and to find the answer is a problem if you don't know where to look for in the first place. Redesigning help wouldn't help much IMH. What could help is maybe adding easy examples with screenshots to help pages, especially the "Using Ultra Recall Part".

My suggestion is to read help file before you actually start looking for a help, ie. take help file as a guide that you need to read before you want to use the program. Maybe you will realize that you actually don't need help because you already know how to achieve sth ...

[Quantum7]

Same experience here. The help file seems useful & pretty complete. Some inaccuracies ofcourse, but nothing glaring sofar.

I was actually surprised to see the "improve help file" item on the roadmap; doesn't really seem urgent.

[tfjern]

Quant -- your nickname, "Geek," perhaps explains why you are apparently having no difficulties whatsover figuring / finding out UR's intricacies and idiosyncracies. But for the rest of us mortals (who are not blessed with a techie cognitive style) the UR help file and online videos are woefully inadequate.

You wrote, "People are LAZY to look for [the] answer," but on my part, at least, this is not the case. As I wrote before, though I discover many handy tips and tricks by roaming these forums, this is not the most efficient way to learn about the program, especially when those giving these tips are often not exactly models of clarity.

Kinook needs to overhaul drastically the help file and provide more user-friendly videos for the non-geeks. Even though I'm sure I haven't tapped even half of UR's potentials, I think UR is the best of its kind on the market, I use it everyday, but its help file and online videos need improvement.

[$bill]

Originally posted by tfjern
the UR help file and online videos are woefully inadequate.


Absolutely NOT true for me. I find UR to be very well documented and the documentation is kept up-to-date with the frequent releases. The example databases and online videos were enough to get me started. The forums are responsive and helpful...I continue to read them to uncover how others frame and solve problem with UR.

Now that you have expressed your frustration may I suggest that you provided a detailed example of what would help people with your cognitive style which apparently is different from mine. What can't you accomplish and why do you think you can't accomplish it. What about the videos is not "user friendly".

Originally posted by tfjern
thanks to these forums I am "discovering" one by one, but is this the best way to learn about the program?

My years of experience as a teacher, mentor, coach would lead me to say yes....all the features are listed in the help...why and how you "discover" them is probably related to what you already know and what you need to do when the "new" information comes into view.

I suspect that it is the concepts of database design that are holding you (or others) back ie how do I solve this problem with a database using UR.....I think more example videos and paragraphs will allow more users to get started "painting by numbers". I think becoming a real database artist requires something different-probably the ability to "think database style", mentoring and a lot of practice. I wouldn't expect Kinook to provide that.

[ashwken]

Originally posted by $bill
I suspect that it is the concepts of database design that are holding you (or others) back ie how do I solve this problem with a database using UR.....
Yes, one of the first hurdles I had to overcome was translating UR terminology to terms that I was familiar with (Attribute = Field, Item = Record, Parent Item and Child Items = Table, almost).

Translating design concepts has been a little trickier, and there's some things that you just can't do yet.

Understanding UR terms and concepts is a learning process and can be frustrating.

I would echo $bill, post a particular problem and we'll see if we can help.

[tfjern]

Let me try one more time to get my simple point across (though I will have to repeat a few things first):

First, UR is an excellent product, no doubt about that, so far the best of its kind (I've tried most of them from AskSam 6.1 to OneNote 2007 to you name it), though I'm sure I have a lot more to learn about the various and powerful intricacies of UR (yes, by pouring over the admittedly well-organized help file and roaming these forums for useful tips and tricks). Those of us who have purchased the program want it to succeed commercially for the obvious reason that I want UR to stay alive and healthy and eventually conquer the entire computer world. The last thing I want to do is transport all the information I have already stored in UR onto another program if, Heaven Forbid!, UR is discontinued for, say, a lack of new customers.

Second, the documention / help file and four online "videos" are not suitable to attract and satisfy new / potential customers who among other things lack the advanced computer expertise of the Senior Members who have chimed in with various comments above, comments such as:

"Understanding UR terms and concepts is a learning process and can be frustrating."

Yes, we should all work hard to learn new terms and concepts, but wouldn't it be better to provide more user-friendly documentation / online videos, esp. if, to repeat one last time, we expect UR to attract a lot of new customers? And perhaps this is one reason a revamping of the help file is on the roadmap, and hopefully not because a few lazy or slow-learning purchasers keep harping on this issue.

[$bill]

tfjern, I did not miss your point, perhaps you missed mine or don't know the answer to my question. That is ok.

Paraphrasing:

tfjern> UR is excellent and I want it to succeed.
We agree.

tfjern> Learning to use UR is difficult and frustrating for me.

$bill> Learning to use databases effectively requires work and study.

tfjern> It is because the instructional videos and documentation are not user friendly for people who lack advanced skills.

$bill> I think the skills that you bring to the table are a major factor in what you will be able to do with UR.

We are not that far off here....

tfjern>overhaul the help file

$bill>What would help you or would have helped you?

My point - I would like you and others to offer specific suggestions if you are able to. As you pointed out, Kinook has already has "revamp the help file" on the roadmap.

ashwken gave a good example of suggestions that are needed. "one of the first hurdles I had to overcome was translating UR terminology to terms that I was familiar with (Attribute = Field, Item = Record, Parent Item and Child Items = Table, almost)" ...This comment could be implemented as a section of the help file dedicated to "for experienced database users".

If you don't know yet what you don't know- the forums are a great place to hang out!

[lazlo24]

Hi all.

So far, I have always found the documentation suitable for task. The biggest problem has been knowing what the program can do. Once you get a new concept identified, the documentation on how to use it exists and is normally good. Understanding what is possible is the real issue here.

Digging through the forums has brought forward new concepts and ideas of data structures, layouts and integration. Ideas that would one may not have had on ones own. Seeing how others have customized, searched and organised has often inspired me to further focus my tool, and lets be honest UR is 'my (your) tool'.

With such a super configurable program as UR is, the challenge is how do you capture all of it's power when so much is how you use it and configure it to view your data. My layout has sliding frames and an overall layout that would drive most people nuts. The searches don't make sense, except to me and the structure would drive most people crazy but to me it suits the way my mind works. I know almost everytime I have dreamed up a concept that would be useful to have, UR has it available once I search the help file for it. The real problem is 'How do you express ones creativity in a help file?'

I do not believe that UR will ever make it mainstream. It believe it is just not suitable for the masses (It requires work to really get the best out of it). Where it make PERFECT sense is for those of us who are trying to deal with and organise the zillion pieces of digital data that constantly bombard us on an daily basis. Don't get me wrong. I love UR and it is the ONLY tool that could cope with the amazingly complex game of intensive knowledge work and I promote it to anybody who I come into contact with who shows interest. (UR & GTD Rock!). What I have found thought is most people are not interested in being that organised.

Is that what you have found or is it just my associates?

[tfjern]

Lazlo24 wrote:

"So far, I have always found the documentation suitable for task. The biggest problem has been knowing what the program can do."

To beat this dead horse one more time: for several reasons I won't go into, programmers are characteristically hopeless when it comes to explaining -- IN SIMPLE, CLEAR ENGLISH -- how the programs they created actually work. That's why programmers are strongly discouraged from writing manuals for the general public unassisted. This is hardly a startling revelation.

Once again, and hopefully for the last time: the available resources -- a "suitable," well-organized, help file and several short online "videos" -- do not explain to average people -- the people we need to get UR to "go mainstream" -- what the program can actually do.

If Lazio24 is right: namely, the program itself is intrinsically too difficult for average users to understand, implying that no amount of simple explanations will be possible, then it is only a matter of time before our beloved UR dies on the vine, so to speak.

But then again, with more user-friendly resources, esp. easy-to-understand online explanations and videos, perhaps the program could go mainstream, provided the programmers, and the advice of certain condescending senior members ("Go Forth and Search the Forums, O Lazy Ones!"), keep their hands off them.

[quant]

Originally posted by tfjern
If Lazio24 is right: namely, the program itself is intrinsically too difficult for average users to understand, implying that no amount of simple explanations will be possible, then it is only a matter of time before our beloved UR dies on the vine, so to speak.
several users here already suggested, that UR probably never make it as a mainstream application. It is only as difficult as you want it to be, because it is so customizable that the only limitation is your grey matter. The simple videos could certainly help, but then when you come to your database, you have to think ... how to do this how to do that ... and many people are either lazy to do that or simple don't have the capabilities (I'm not saying that they are stupid). Also, as was already mentioned, it depends whether you had contact with databases before, I had two University semesters on databases and it took me a good month to get a grasp of UR (not because it is difficult, but because it is so customizable), so you cannot expect to jump to UR and "know it all" as if by magic if you've never heard of databases before. Kinook would have to make several videos with simple database concepts and design, starting with a map and showing how it translates to UR database.

I agree with you that more videos would help (I myself wanted to make one on layouts and put it to youtube, but I coudn't make the sound and video work together on camstudio), but whether this itself would translate into more happy users of UR, I'm not so sure. But certainly worth a try ...

[dspady]

I think tjfern is right. The documentation is not readable for the individual who is not particularly computer programming or database literate. I use UR now, and do so because I like what it can do, even for a simple database. I used others, and at times wonder if I should go back, because their explanations of how to do something are more clear.
I learn a lot from the forums and people have been very helpful to me when I have had any problems, but it is nice to be able to go to the help file and have an unambiguous description of how to do something simple, or some sort of switch to make it easy to implement within UR, rather than going to an arcane folder to do something. (Kinook's instructions as to what to send when there is a problem is a good example of this.) Another one (I just looked this up as an example, has to deal with layouts. Much of what is said in the help file regarding layouts is fairly straightforward, although I still really don't know how to make layout changes and save them. An example of a, I think unnecessarily complex, request is the following:

Note: Customized layouts are stored in the user's application data folder (%APPDATA%\Kinook Software\Ultra Recall or C:\Documents and Settings\<username>\Application Data\Kinook Software\Ultra Recall). To reset all layouts to their defaults, exit Ultra Recall and delete all Layout*.dat files in the above folder.

Now, it is fairly straightforward, but it should not have to be done. Why can't I reset all layouts to their default within UR?

I think a big part of the problem is the use of jargon, which should be avoided if at all possible when creating help files. Assume intelligent, but ignorant, individuals will be using the program and proceed from there.

I think also, that UR might be more 'approachable' if there were several working examples of some of the more complex database uses of UR. This is asking a lot, however.

This is a bit of a rant, and for that I apologize. Basically, I want to say that I agree with tjfern.

[janrif]

One of the ways to help solve this is for users to offer their urds to a forum of sample databases. This might help others see what is possible. I'm happy to do that once I get it a bit streamlined.

[dspady]

I think that another discussion going on in this forum at the present time "Numbered lists possible" is a good example of the need for clarity in the documentation. The answer was provided by the forum, not by the help file.

[quant]

Originally posted by dspady
I think that another discussion going on in this forum at the present time "Numbered lists possible" is a good example of the need for clarity in the documentation. The answer was provided by the forum, not by the help file.
what do you mean? There is explicitly in the help file among virtual attributes

"· Tree Order: this number value will is the position in the Data Explorer/Search pane (NULL value if sorted alphabetically) "

What do you want, the help file to have some neural network artificial intelligence to give you answer to any of your question? (+ see that thread that even posing a question is sometimes a problem itself)

[dspady]

As far as the specific question, I have no particular interest. I am just pointing out the fact that it took a 5 message dialog for an individual to find out how to do something. Maybe it is in the help file, and I got the feeling that the original poster had looked in help (I could be wrong), but it still took a forum dialogue to sort it out.

[janrif]

Come on, Quant, I don't think you're not being fair here.

While it's entirely possible all questions are answered in the help file -- and I don't doubt that -- I think what you are seeing is a frustration with understanding what's written.

Help files are notorious for being written badly because they are usually assembled by engineers & while engineers understand & can explain the actual workings of some function, that's entirely different than offering a "how to" accomplish something.

I have the feeling that most user questions would be "superficial" like mine: Can URp number the items in the related items pane? The answer is "no". However a partial workaround might be accomplished this way: step 1, 2, 3 etc.

I have not looked at the Help file carefully so I can't offer any comments about possible improvements @ this time but I can say that -- even though I have a basic understanding of UltraRecall jargon -- I, too, have been mystified by sections of the help file at times.

[tfjern]

Quant / Senior Member / Geek? wrote:

"What do you want, the help file to have some neural network artificial intelligence to give you answer to any of your question?(+ see that thread that even posing a question is sometimes a problem itself)."

Let's ignore for now the clever sarcasm in the first part and try to focus on the enigmatic contents of the second part (in parenthesis). Let's see: first, I guess we'll have to do a systematic forum search for "that thread," next ....

On second thought, it might be better if kinook, by expressing its frank opinion or some helpful comments on this documentation issue, mercifully brought this thread to some kind of conclusion, but I guess that might bruise some egos.

[quant]

Originally posted by tfjern
On second thought, it might be better if kinook, by expressing its frank opinion or some helpful comments on this documentation issue, mercifully brought this thread to some kind of conclusion, but I guess that might bruise some egos.
well, they made it clear already by including "revamp help file" in the roadmap, and I don't have slightest problem with that ;-)

And more videos, tutorials, sure why not ...

maybe I should start worrying about this forum to die due to lack of "how do I ..." threads :)

[vogelap]

I am a longtime computer user (my first was a Commodore Vic-20) and have written technical documentation for variety of software applications, everything from BBS doors to Content Management Systems to E-mail Clearinghouses to CRMs.

I find URs documentation to be aimed at programmers and above the head of power-users like me, let alone the common user.

I love that UR has documentation. I really do! But I think there would be a lot more UR users if the documentation was written at a consumer level.

I would be willing to help with such an undertaking, if there was interest and a team.

[tfjern]

As far as this loyal customer is concerned, UR is the best in its field (I use it everyday), but as for the "documentation" ... it's, well, about the worst, for some of the reasons (e.g., user-unfriendliness) cited in some of the posts, above.

So Kinook, please get the lead out and start the revision process (cf. Luke 6:30). We are not getting any younger, you know.

[mikeg]

Good thread; important topic. At least everyone here can agree UR is the greatest and that Help could benefit from an update. UR Help is FAR from the worst I've seen though. Obviously it could be improved for beginners, less technical users and even for technically-inclined power users who need to find/understand advanced topics more quickly. But ease-of-use and comprehensive feature coverage are difficult to achieve in part because UR is so massively feature-rich.

As quant mentioned, Help revamp is on the roadmap. Furthermore, it's scheduled for the next release! This is an enormous undertaking that will impact delivery of other important enhancements. We could be in for quite a wait unless Kinook can bring in documentation specialists. This would minimize resource contention between documentation and development plus--to echo Drew's point--developers/engineers are typically not the best at explaining their creations to the layperson.

Providing better quick-start Help for new users should be the highest priority. After that, I have the same wish as tfjern and everyone here (as far as I understand it). Geeks/power users don't mind digging through advanced help, online articles and discussion boards for obscure or sometimes undocumented tips. However, the thrill of discovery and pride of hard-won knowledge eventually wears off as our attention is needed elsewhere. Then we just want to find/understand information quickly--ideally without having to search in more than one place.

It has taken Microsoft many years to even approach this ideal with integrated local and online Help, ability to filter results by technology/area of focus, multimedia content, and (increasingly) clear, helpful articles that usually link to related materials. To create something like this is almost an industry unto itself. Only a few elite businesses can afford the resources and infrastructure.

In the world of relatively small vendors, Kinook is already an overachiever in terms of functionality. As for the Help update, incremental progress may be a reasonable goal/expectation.

[$bill]

Quoting Jacob Kaplan-Moss on what to write (Writing Great Documentation series http://jacobian.org/writing/great-documentation/ 11-2009)

"Tech docs can take a bunch of different forms ranging from high-level overviews, to step-by-step walkthroughs, to auto-generated API documentation. Unfortunately, no single format works for all users; there’s huge differences in the way that people learn, so a well-documented project needs to provide many different forms of documentation.

At a high level, you can break down the different types of documentation you need to provide into three different formats:

* step-by-step tutorials,
* overviews and topical guides to the various conceptual areas of your project, and
* low-level, deep-dive reference material."

To their credit, Kinook's documentation covers all of these areas. The strong area is their low-level reference material which is especially through and current with each release.

I would advocate ADDING to the documents available rather than replacing or rewriting what we have. I would place the emphasis on NEW "overviews and topic guides" written in a different styles and/or delivered in a different format. New uses really need to 'get' the concepts of UR to use it effectively.