Great product...lousy documentation

DEVONthink Feedback
1

I only partly say this tongue-in-cheek when I ask “wouldn’t you like to hire me?” :laughing:

DT looks like a great product; I see it recommended all over the place, and I’ve finally bought the Pro version. This is the second time I’ve demo’d it; I gave up the first time (around late 2009, early 2010 I think).

This time I’ve bought it out of necessity in order to complete my MA dissertation in Technical Communication. And there’s the irony: my MA (and my work) is in producing effective user assistance and documentation.

Without putting too finer point on it folks, DT’s manual is a disaster! Full of unnecessary sales jingo (trying to convince someone to buy something when what they’re looking for is information on how to use it is counter productive) but worse, lots of places where statements are made about what you can do with it with no explanation of how those tasks are accomplished. No proper user tutorials, no screencast how-to’s…come on guys, even open-source stuff like GIMP has more help.

You can do better than this (and if you want to hire a freelance technical writer to do it, let me know… :wink: ).

2

Maybe people don’t really use manuals?

Anyway, Joe Kissell’s Book, Take Control of Getting Started with DEVONthink 2, is a classic reference.

This forum is full of gems of advice and how-to.

3

Some people do use manuals. Thankfully, I did purchase Joe’s book and I would recommend it highly to anyone interested in learning how to use DevonThink to its fullest.

4

I couldn’t agree more with the OP. DTPO is a very complicated app with many functions which are very poorly explained int he documentation. almost all of it presupposes some other information. For example, when you are trying to use folder scripts it says “use the folder setup utility” but never says 1. where this utility can be found or 2. how to use it. You can spend an hour just tryingt o get simple informastion that would have taken the designer five minutes to explain.

While I have bought and enjoyed Joe Kissel’s book, it falls way short of being a manual. Can you imagine buying a Porsche and being told to go out and buy a third party book to learn how to use the air condition system? Kissel is mainly interested in using DP as a filing system. Look at the scripts section, he basically refers readers rto the Devon Academy, which I assume is now defunct.

Devon is not alone in this trend, hence the market for the Missing manuals books. But it strikes me as very short sighted by the company. The one consistent complaint I see online is how hard the software is to use and its “steep learning curve.” Just imagine how many more customers you would have f you could reduce the learning curve. Thats what marketing is all about. And what would it take? A clever writer and a few days’ work.

5
  • 1

I heard so many good things about DevonThink. I am trying it for the first time. It seems unbelievably badly explained. The documentation is really poor which is a crucial problem because the interfaces on the app themselves are counter intuitive. This product really needs a simple well organised walk through to all its major functions.

6

I whole-heartedly agree.

Folks such as korm are very generous with their posts and advice. But, these cannot take the place of clearer documentation from Devon.

I read manuals, too. The Pro Office manual is a mess of confusing and poorly-written feature descriptions (and needlessly includes thirteen completely irrelevant pages of Release Notes from time immemorial – better separated into a separate document). The manual explains core concepts only vaguely, and sloppily at that. Third-party books should not be necessary to understand the basics.

Devon Think is a complex product. It deserves some sort of cookbook that not only lists features and clearly describes what they do, but also the consequences of using them, and how they interact. This cookbook should lead the new user through a series of steps that build a database from scratch, starting with establishing a clear set of goals, and illustrate the path to meeting these goals with words, tables, pictures, screencasts, and examples.

I’ve had Devon Think since last November, and I’m just now starting to think that I understand how it works, and how to work it. But, I could be all wrong.

Devon, please take these complaints to heart. We need help understanding your product.

7

Actually, we are listening. The current documentation has a history: First we had a true manual that explained concepts and tasks, but with the frequent improvements we made to the app it soon became unmanageable. And people complained that we didn’t have a menu-by-menu and button-by-button description of all elements of the app. So we decided to go for a documentation that explains all details of the user interface, with the benefit of much better manageability with future changes to the app. So, technically, the current document is (as good as ever possible) complete and accurate.

It is, however, no manual. But I have plans to extend the documentation with the “Common Tasks” chapter (analogue to what’s already in the DEVONagent documentation) — short sections that explain how to use DEVONthink for common everyday tasks. In addition we have the slideshow tutorials that pop into the user’s face every time he opens the app (through the Welcome screen).

And, because we know that the documentation is no manual we engaged Take Control Ebooks to write an ebook that complements the built-in documentation.

For improving the documentation I would definitely appreciate your help: please point me to sections that need improvement, contain too much “marketing blubber”, etc. (best by email to eboehnisch(at)devontechnologies.com). The more concrete feedback I get (not a general “the thing is rubbish” but more a “this section is superfluous” or “be more specific here”) the easier it is for me to improve it.

Eric.

8

Eric, I am very happy to read that you have a plan in place for enhancing DT’s documentation.

A section devoted to “everyday tasks” sounds intriguing and very practical, and would be a welcome addition. This section might begin with a “quick-start” guide to setting up a database to manage information for a specific project, and continue with “advanced topics.”

I also recommend, even in an “everyday tasks” discussion, a thorough discussion of Groups and Tags, which would include a description of how DT’s artificial intelligence works with them, similarities and differences between them, and specific recommendations for using them. An “everyday tasks” example might be an ideal place for this discussion.

I will contact you off-list with observations about the current DTPO manual, as well as the web site and the forums (all of which to me are part of the overall documentation set for DT). And, thank you for soliciting input.

There is another entire dimension to DT which I believe should be documented. I call this “using DT on a systemic basis.”

By this I mean: it is one thing to use DT for managing information dedicated to one purpose, such as research for a book. It is another thing to use DT as an information manager for multiple projects, each of which would use information contained in an underlying data store. My primary interest in DT is in the latter use case.

I have several active book projects. Each may reuse research which I keep in a folder called “Background Material.” This folder contains many sub-folders which cover topics ranging from science, the arts, psychology, religion, technology, and so forth. This structure is well-organized, but suffers from having the rigid, hierarchy-only view that Finder (and other file managers and operating systems in general) impose. In order to relate topics, I must manually create aliases to documents and manually place these aliases in other folders. This is a time-consuming task, and the process is difficult to manage, and the system easily fails.

My ultimate use of an information manager like DT would be to place all of the information in my Background Material folder under management, to take advantage of contextual full-text search and retrieval, help me discover relationships among my research documents, and allow me to associate documents with each other.

For a specific book project, I would select folders and documents from my central database, and DT would help me manage information about my book’s characters, locations, and so forth, along with the underlying supporting research documents.

Planning and in-depth product knowledge are key in designing and implementing such a systemic use of DT. And, while the information that I need to figure out how to do this may be in the manual currently, I must tease it from the manual in bits and pieces.

And, one’s computer set-up must be considered as well. For example, I keep all of my user data on a hard drive partition separate from the boot partition. However, I may need to change my partitioning scheme, and by moving the location of my documents, I would lose all of my indexed DT data. I could import data into my database, but then, this data is not available for reuse among project-specific databases. I could just keep everything – Background Material as well as projects – in one giant database, but from what I’ve read, this is not recommended due to the way that DT’s artificial intelligence works. This is all quite a dilemma. Granted, Devon is not responsible for my choices in setting up my computer, but I need to thoroughly understand the implications of my choices upon using DT, and understand the pros, cons, and options available for the different implementation models.

I have so far only implemented several project-based databases. I am already running into issues about how to reuse documents that I have placed into these databases.

Current technology my not be up to the task of such a “systemic” use of DT, but I would like to understand how far I can take this idea, and advocate for enhancements to DT and OS X to accomplish this goal.

In implementing such a system, there are many questions that must be evaluated, and many decisions to be made. I hope that you will consider this use case of DT in your enhanced documentation.

Many thanks, again.