Proposal for downloadable tutorial/example files


The user guide/help/reference materials for DEVONthink are spotty at best, incomplete, and even wrong in cases where application development has resulted in changes from documented information. For experienced users, Version History notes are often the best references for new or changed features, but that’s a terrible source of information for less experienced users.

It’s not surprising that the most consistent thread of comments about DEVONthink on the user forum is about inadequate documentation, especially the kind of documentation that helps users understand what they could do using DEVONthink, and how to attain their personal objectives for the application.

DEVONtechnologies is a small firm. The developers are, quite properly, putting their resources almost exclusively into application development, not the user documentation.

So DEVONthink itself is becoming one of the most powerful tools available on the Macintosh (or any other platform, I would argue), but the existing user documentation doesn’t give new users clues as to how to approach that power.

Should DEVONtechnologies devote more resources to user manual and help documentation? Yes – certainly in the long run – but that’s a daunting task, especially as the application will continue rapid development and changes. Many years ago, I wrote the user manual for a useful little Apple II database program put out by Silicon Valley Systems. That was easy – the application was a one-time development effort. I don’t think I’d like the job of writing complete user documentation for DEVONthink.

Meanwhile, there are two other ways DEVONtechnologies can help users. The first is already in place, the user forum. The forum is very active and provides users an opportunity to ask questions and discuss features and tricks. (Even here there can be problems, because answers to questions that were appropriate at the time may now be incorrect because of terminology or feature changes.)

The second important user assistance effort should be downloadable tutorials covering a variety of topics, and available from the DEVONtechnologies Web site. These would be modular items, easy to import into or delete from one’s DEVONthink database, addressing common user queries, tips and tricks, troubleshooting and introductions to new features.

This kind of effort would require relatively small resources from DEVONtechnologies but could be important to drawing in and assisting users, with positive impacts on marketing and sales. Modular tutorial/case example files would be easier to update than a formal user guide, when changes are made.


[1] The medium

What better medium than use of DEVONthink groups and files, exported (File > Export > Files and Folders) and archived (ZIP or DMG), that can be imported (File > Import > Files and Folders) into a user’s database? The topic can be written in rich text, providing tools such as screen shots, hyperlinking and Wiki linking as appropriate for the task. The very use of this medium would familiarize users with what can be done in DEVONthink!

After reviewing the topic, the user can choose to keep the tutorial file or to delete it.

[2] The topics

Useful topics can be gleaned from queries to DEVONtechnologies Support and the user forum. These could range from topics appropriate to first-time users to those useful to power users. Certainly, changes of procedures or terminology in the application and introduction of new features would trigger corresponding topics.

I’m a proponent of tutorials and case examples, even if there’s a well-done user manual.

The best way for a new user to learn DEVONthink is to play with it. The value of tutorials/case examples (especially for a blank, new database) is to encourage and assist the user to learn by doing.

Very few (if any) people start learning a new application by reading all the way through a user manual. In fact, I’ll maintain that a well-done user manual for a rich and deep application such as DEVONthink will seem daunting and incomprehensible to someone who is approaching it for the first time. That’s not putting down the value of a reference manual, which becomes more and more indispensable as the user learns the application and begins to use it to explore features and for troubleshooting.

Even experienced users can learn new features, examples of what can be done, how-to, etc. from tutorials/case examples.

[3] Development of tutorials/case examples

DEVONtechnologies staff can use this vehicle to enhance user support and to provide documentation and illustrations of new features as they are introduced. If I were DEVONtechnologies (which I’m not) I would view this approach as a good way to support users and satisfy demands for documentation – and even as a good approach to lay out and help maintain more formal application documentation. Why? User satisfaction will lead to more sales – hence more users benefiting from DEVONthink.

Queries and discussions on the user forum can be ‘mined’ for interesting topics. It would probably be a nice touch to give attributions to those who make interesting queries or comments.

Finally, it would be a good idea to invite users to suggest topics, or even to submit tutorial/case example files to DEVONtechnologies for consideration. (Isn’t there some old Chinese proverb about using off-payroll volunteers whenever you can?)

[4] Maintenance and quality assurance

Maintenance and quality assurance of the downloadable files should be the responsibility of DEVONtechnologies.

DEVONtechnologies staff should monitor feedback from Support queries and the user forum in order to continuously improve user assistance.


Excellent idea!

What about making it a blog with links to the documents, so everybody gets infos about new document modules?


Bill…this is EXACTLY what I’m talking about.

You and I seem to learn how to use software in the same way. The first thing I do is look for a “quick start guide” type of document. If I find one, I read it. Then at that point I go play with it.

Now, the first time I demoed DT there was no such document so I just started playing with it, and with an app like DT that approach is less than fruitful. You’ve got to be in the right frame of mind and be willing to exhibit a certain degree of patience. At that time I wasn’t. I was aggressively looking for solutions to certain, specific process challenges and after what I considered to be 15-20 minutes of screwing around trying to figure out what this app does, I said ‘screw it’ and deleted the program. I didn’t get the paradigm and never started getting traction with how to use the app and what it could do.

I sympathize with DEVONtech because they are caught between the horns of a very common dilemma: keep pushing development of the app while letting reference material become increasingly irrelevent, which makes power users happy but makes it difficult for folks like me who are casually trying out the app to get interested.

Or, they could slow development of the app while devoting some of their limited resources to usability issues such as user docs, quickstart guides and/or tutorials. This frustrates power/long time users and deprives the app of attractive new functionality, but it allows more casual users to better learn how to start effectively using it.

My personal inclination here is, like with most aspects of life, to strive for balance. I’ve seen software companies get hurt in both directions. I’m very excited DT is about to be releasing new, more powerful versions of their products but assuming that for every one post expressing a view point there are dozens of silent users holding the same perspective, DT has developed themselves into a corner and waiting 6-12 months while developing accurate and complete user doc is not only going to suck away resources but will unacceptably delay the creation of usability tools, and THAT is going to cost them dearly in lost sales.

Developing tutorials/example sets can be done with help from the user community, can certainly be done more cheaply and quickly than developing current user doc and will likely be even a more effective sales/demo tool.

I will re-iterate, though, that in addition to these tutorials I think DT could really benefit from something akin to what the guys over at have for Notebook, a video tour that introduces the user to terrific feature set of that wonderful app. Show how to capture information, store it, organize it, link to it, use the ‘see also’ functionality to leverage into related materials, etc… Then the user could use the tutorials to now play with what they just saw done.

I played around with a demo of Notebook and thought it was cool, but after I spent 15 minutes watching the video tour I gave them my money. DT could really benefit from a similar set of tools.

What about an on-line Wiki that could be added to and maintained by everyone including DevonTechnologies and users. most Wiki’s allow people to recieve emails when particular topics have changed.

I had suggested this idea a while back (on the beta forum; if you have access: … highlight=); it seemed to be a moderately well-received idea amongst a few users. However, the DEVONthink staff made it clear this was a low priority for them, so a Wiki would likely have to be a user-initiated project. (Actually, in that same thread, we had already started talking about shipping DT Pro with a pre-populated database with tutorials, etc.)

I had planned to wait until DT Pro made it to PUBLIC beta before bringing up the idea again. (Although I assume we beta testers are under a disclosure agreement, you’d never think so given that the DT Pro beta features seem to be publically discussed here regularly.)

Anyway, I’ve been playing with PMWiki, gotten it up and running, and have really wanted to have a “living document” of DEVONthink pro hints / tips / tricks / and ideas.

If the developers were OK with one of us starting a DEVONthink Wiki, I think this would be a great idea. Although I’m busy, I’d even be willing to try hosting it.


I like the wiki idea. When I was learning how to use DateBK, I found this document very helpful:

It is a user-made document in that if you had anything to add, you e-mailed the owner. A wiki-type of document (a la wikipedia) would remove the middleman, so to speak.

I’ve used several public on-line Wiki’s to host Wiki’s related to my development work. I’m currently using XWiki which seems pretty good and is free. Certainly worth a look.

Took a look at the manual for 1.9.2 and came away feeling that is is improved over early versions of the manual.

There are some minor glitches (and I couldn’t get at the screen version), but it does have good “quick start” features.

The usage scenarios are suggestive, but I still think some tutorials would be very useful. I also agree with the suggestion made earlier in this thread about some illustrative movies, like those on the Circus Ponies NoteBook site. Examples and “show and tell” elements on the DT Web site would both attract new users and get them started with more confidence. Other good examples of this are the downloadable examples and tutorial movies on the AquaMinds NoteTaker site. AquaMinds’ PDF user manual is one of the most attractive and useful manuals I’ve seen.

Bill –

I think you are right. I have “tried” DT three times, always wanting to adapt it to my environment. I have generally been nonplussed by the manual and “scenarios.” Seeing something like a sample DB with key functions demonstrated would be a big help and would attract potential users who are “on the fence” or confused.

in fact, this sounds like a really intriguing idea. We’re currently discussing this internally, but if someone starts and host a DEVONthink/DEVONagent Wiki, it should be us.

In one of our web site surveys, most people wanted documentation both online and in PDF. What about the following setup:

PDF documentation listing all features, commands, window gadgets, etc.
Help files containing the documentation in HTML form
Example database (DEVONthink only)
Online Wiki with tutorials, hints, tricks, ideas, etc., as you suggested

Could this be an approach that makes sense?


Funny, I was about to come on here and post that if DT wasn’t going to coordinate/drive this thing I thought it was a bad idea at a number of different levels, if for no other reason than it’s not the user community’s responsibility to tutor a company’s users, it’s theirs, and if they didn’t want to participate why should paying users take their time to do their jobs for them? I’m very heartened to finally see someone from DT chime in here.

One note to clarify, i think user participation is great, just needs to be driven by DT.

what ERic proposes sounds good. I still think you need an introductory movie along the lines of what circusponies does with Notebook to give prospective new users a reason to even start getting traction with DT.

I’m definitely all for it. The problem I could see coming up is just the sheer number of different ways to get support. You didn’t even mention this bulletin board, which is where a lot of people turn for help!

I could could imagine that PDF, HTML, phpbb, wiki, an example database, AND a movie tutorial would be … overwhelming.

I just wonder whether phpbb and a wiki would be a bit redundant. But as much as I like this bulletin board, I think it’s NOT the best place to put usage scenarios / tips+tricks, because the posts get lost, and perhaps a wiki would be better. On the other hand, I think this phpbb is a great place to post a quick “I have this problem” sort of question, and get a quick response from the gurus.


And hard to keep current. This is why at least the PDF documentation and the HTML help should be identical (= one could be generated out of the other without manual intervention). This is especially important with the fast evolution of the applications.



BTW: Any comments on the DEVONagent manual, which is a different style?

fyi, the purpose of the intro movie isn’t as a help resource for users but as a way for people trying to gauge if this app is worth downloading. This is a VERY difficult app to get traction with. Unless you are very dedicated to really trying to drive yourself down a learning curve (uncommon for casual browsers), you’re not going to get what this app can do for you.

I’m willing to bet a lot of money that DT gets a LOT of people who hear about the app, check out the website, maybe even download DT, play with it for 5 minutes and say ‘screw it’.

I did that myself about 8 months ago. They are losing a lot of business they could use to fund extra personnel who could fund extra development.

I don’t care how great the app is, you’ve got to sell it if you want to be around for the long haul. DT, in my opinion, has two main weak points:

  1. it’s tough to figure out exactly what this app can do for you without giving it a very thorough demo

  2. even if you want to give it a very thorough demo, you are essentially on your own trying to figure it out because there are virtually no resources to help you do this.

DT needs to address BOTH these issues.

All the above mentioned intitiatives are very welcome and very useful, but don’t alter the fact that a reliable and thorough manual remains absolutely indispensable: wikiwiki’s, tutorials and whatever you like can never take its place.

Is it a daunting task for a small company to write an extensive manual for an application like DT? Yes and no. Yes, if you first develop a whole new (version of an) application and then, in extremis, try to put together some kind of written guide. No, if you take the habit of describing every new feature as soon as it has come into existence. For those who have this fixed habit, composing a manual should be a much less time-consuming and frustrating experience.

Maybe I’m wrong, but I have a vague idea that the guys of DEVON don’t work that way; and what’s more: something tells me they feel an unconfessed but profound dislike for writing manuals, which they experience as an activity which deprives them from precious time they would rather invest in developing new features. If I shoud be wrong, I apologize; if I’m right, as I suspect I am, this means that they will never write the thorough manual many of us desire so dearly, because they will always have new features to develop, and that someone else will have to do the job.

Time will show. But in the meantime, why not add a new section to this precious forum, exclusively dedicated to (additions and corrections to) the existing manual? The postings in this section, which undoubtedly would be numerous, would certainly make it possibile to improve the manual rapidly without investing too much time.

timotheus…great idea.

i’ll take your initial concept/observation a step further. imo, a sound software development process isn’t one guy just messing around and seeing what he can do. hopefully you have a development curve you want to move DT through. You have functionality you want to add now, and some you want to add later, and some you want to add if you all win the lottery and can afford to work without financial constraints.

ideally, before coding begins some kind of design document is created that lays out what you want to do, why you want to do it, what the screen layouts will look like, what db mods need to take place to make it happen, and a set of test cases to ensure it was coded properly. A well written design doc can and should serve as the basis for the accompanying user doc. if these are viewed as totally separate tasks and deliverables, then my guess is the design process is being handled in a very informal, non documented manner.

or put another way, write a good design doc and your user doc is 80% complete already.

another observation is that those who code without design docs usually take longer to produce buggier software that takes longer to test and re-code than those who invest a bit more time upfront to document and communicate (both to others and themselves) exactly what they want to do and why, along with how.

I agree that a detailed, well-written, menu-item-by-menu-item manual is required. But, I’m not sure I agree that it would have been possible for the DT people to write the manual as they developed the product. I seem to recall that the features / user interface details / etc. were constantly in flux during the alpha stages of DT Pro development, so writing a manual at that time would have constantly needed revision as the product itself changed.

That being said, it seems that the pace of DT Pro changes has slowed considerably, so getting the manual done now makes sense.

Devlopers: Is there any sense when a draft copy of the DT Pro manual will be available? I’m sure you’d have volunteers amongst the beta testers to start proof-reading.

We’ve already started with one or two chapters, but other things draw our attention right now, e.g. the transition to a new online shop system. It will evolve over the next weeks, though, and yes, we’d hope to be able to ask beta-testers to proofread them.



Quod erat demonstrandum.