Discussion on improving documentation

[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.