When will we see better manuals for DT and DA??

In another thread on this forum the need was stressed for better and more thorough manuals for both DT and DA. I completely share this view. The actual manuals don’t really deserve that qualification: they should be better termed ‘introduction’, ‘presentation’, or something the like. They touch upon a whole range of issues without really discussing them. Just one example out of many I could give: the discussion, in the DT manual, of the various ways in which you can import data into DT (“Link to originals”, “Copy files to database folders”, “Copy files into database”) is absolutely insufficient. The advantages and disadvantages of each of these alternatives should be discussed much more thoroughly, in order to make it possible for the reader to make a well-considered choice.

The lack of guides or manuals worth those names is becoming a real Achilles heel for both DT and DA. As long as such guides won’t exist, many people who in theory are interested in these applications, will never come to really use them.

Moreover, it would be very convenient to have a series of ‘case studies’, by which I mean a series of little papers or essays in which experienced users of (especially) DT explain into some detail where exactly they use DT for, where they don’t use DT for, how they import and store various kinds of data into DT, how they organize themselves, etc. etc. This may all seem trivial to the experienced user, but for a beginner it certainly is not. From time to time one reads something like that on this forum or in Devonnews, but it all remains too short and too episodic.

totally agree.

as much as the apps themselves kick serious a$$, the user doc is absolutely pathetic. In many cases, it refers to menu commands that don’t exist (which means the app changed but the doc stayed static).

here’s my recommendation:

  1. clean up the doc and make sure it’s at least accurate
  2. starting out with preferences and saying to set them per the user’s desire without explaining what EACH one of them is, what they do and how to differentiate between different settings is just dumb. How the hell do I know what they should be, that’s why I’m reading the blasted doc.
  3. Document EVERY command and menu item, explain what it does and how one uses it.
  4. provide basic tutorials that walk the user through the basic functionality of each app.
  5. provide meaningful strategies on how to get the most out of these wonderful applications.

I can’t tell you how much time I’ve wasted trying to figure out how to use this stuff. THe doc is useless, so I come to this board, and while I greatly appreciate the assistance I’ve received, half the responses have referred to a version I can’t use and to functionality that doesn’t exist in the production version, making learning this stuff even more confusing.

you guys have great stuff but you need to stop treating the doc like some trivial thing you need to get around to. I realize it’s not as sexy as coding and testing but for users like me it’s just as important as the core functionality. You can put all the great stuff into these apps you want, but if I don’t know it’s there or don’t know how to use it it doesn’t matter.

Well put, I fully agree with both posts. As a new user I have spent way too much time figuring out how to use DT. That learning curve has kept me from suggesting it to several other people who would ultimately benefit from DT but not have the time or patience to figure it all out. Part of the problem is that as good as the core idea of DT is, it still has a ways to go with it’s overall user interface (as has been discussed on these forums elsewhere). Timotheus’s example of the confusion in the manual about how to import data hits it on the head – and is more confusing because these import methods need development themselves. v1.9 was a big improvement, and I am expecting/hoping for 2.0 to finally bring it to the point where I can recommend DT more freely to less technically inclined users. (for instance, DT developers promise an overhaul in the whole importing methods approach/terminology in 2.0) Getting all these things in line with a good reliable manual is critical for DT to reach a wider user base. Keep plugging away at it DT, I consider it a great app which hasn’t really reached it’s potential yet…

I think there are several issues.

I have worked with technical writers, and I have the feeling that there is a lack of understanding about just how much work is involved in producing accurate and understandable documentation.

in particular, you cannot just let the writers go off and produce understandable documentation, there is a substantial involvement on the part of the technical people who must review the drafts for accuracy. when a passage is rewritten by a writer because it is not understandable, there is a good chance that the writer doesn’t understand it.

add to that the rapid pace of development of the DEVON software, which would force continuous rewriting to keep the documention up to date.

I see lots of ideas and lots of feature requests, lots of interest in the next release.

resources are always limited, and choices always have to be made. at this point in the product development, an excess of attention paid to user manuals can only slow down software development.

it makes a lot of sense to me that the focus remain on development until the product feature set is stable. I think the current manual strikes a reasonable balance in terms of information and maintenance at this point in time, although I agree that the information should be brought up to date.

I agree with this too. Writing a manual is no small task and especially with all the feature changes/development in DT the past year or two. Getting the “feature set” more stable is of course the number one priority. When, finally, all this comes together, a stable feature set and thorough manual, DT will then be ready for whole new expanded user base.

It is certainly true that a good manual can not be written in one day, nor in one week. But on the other hand: the difficulty of such a task should not be overstressed; and there are certainly many more people capable of writing a good manual than people capable of writing an innovative application like DT.

Anyway, I totally disagree with the idea that the focus should remain on development (in other, less positive words: that the documentation should remain more or less what it is now) until the product feature set is stable. To be honest: that’s ostrich policy. Firstly, this moment will probably never come: there will always be new features to develop and new technical adaptations to make. Secondly, this would do great harm to (especially) DT, because it would deprive it of vast numbers of potential users. And of course it would deprive Devon of substantial financial resources.

It seems to me that the people behind these beautiful products, for whom I have great sympathy and respect, are far better in writing good applications than in writing manuals, and that they themselves know this very well, and therefore have a certain dislike for this task. But this does not alter the fact that it should be fulfilled some way. And unfortunately, I must say that in my opinion too it’s not just a question of bringing the actual documentation up to date; I rather think that everything should be completely rewritten by people who know how to make an innovative application like DT understandable for the common potential user, how to make him (or her) enthusiastic for it. A beautiful task for the right person(s)!

But until that happy day will come, something should, and perhaps can, be done. In my first post I ventured the idea of what I called ‘case studies’ about the use of especially DT. Among the experienced users of DT there are certainly many people with clear and detailed ideas about how to use DT and how not to use it; people who know how to avoid certain pitfalls, etc. etc. Many of them have already posted a substantial number of messages on this forum; with some cutting and pasting perhaps it would not be a too laborious task for them to write a a kind of autobiographical sketch pertaining to their use of DT.

Why not add to this forum a section called “How I use DT” (or something of the kind) dedicated exclusively to this kind of contributions? Among the experienced users of DT, there will certain be people who like writing such little essays. They would be an excellent starting point for discussions which could be fruitful even for the experienced user.

As a developer myself I do agree that the investment in resources needed to produce good documentation is enormous and probably much more than most people realise. Having said that documentation is one of the most crucial elements of a software product from the users perspective. If a user cannot work out how to operate the product they will usually lose interest and give up.

DT’s documentation looks good and obviously aspires to be more than the average software manual given it’s coverage of topics such as usuage scenarios. On the negative side it is woefully incomplete with numerous errors and omissions. In DT’s defense it should be pointed out that documentation is an area that most software products fall down on and many products have documentation that is far far worse than DT’s. The development tools I use are frequently criticised for their poor documentation.

Having a great product and great documentation doesn’t guarantee success but by god it helps!

reasonable balance? you gotta be kidding me. there are menu commands, settings and preferences that are either ignored or are in error.

look, I’ve written user doc for applications way more complex than DT and I agree, writing good user doc is an underappreciated art and takes a lot more work than most people can imagine. But I’m not raising the bar very high here. At a MINIMUM, user doc should contain at the very least a basic explanation of every command, every setting and every preference. Ideally, it will provide context to help the user understand why they would opt for one configuration over another. And the best doc actually provides examples the user can follow to act as tutorials to learn how to use the thing.

DT is a great application, but its user doc doesn’t meet even the lowest, most basic criteria for user doc.

It’s something that developer after developer after developer does. They get so caught up in writing and testing code, in fixing bugs and in developing new functionality that they treat the doc as an afterthought. The problem is, they then release this sparkling new product to the world and half the stuff they just spent the last 6 months working on goes unused because there isn’t anything anywhere that explains how or why to use it.

Everyone, including me, is all excited about coming releases but I’ll bet most of us are utilizing but a small fraction of these applications’ abilities. Honestly, I’d be far more excited to get information and training on how to utilize the current functionality than more undocumented features which I have no idea how or when to properly use.

I realize we’re talking a few manweeks of effort to bring the doc current with the next release, and maybe another couple manweeks to put together quality tutorials to help educate the new user on the capabilities of these products. If DEVONtech wants to be successful in the LONG run, they need to pay attention to this aspect of their product. It’s not enough to sell a great bundle of features, you need to help people use your software to solve real world problems. Right now, you’ve gotta WORK to not just figure out how to use this stuff, you’ve got to work to even figure out what the heck it does to the point you’re willing to even demo it.

They need to devote resources to making both tasks easier if they have any serious interest in growing their sales.

We’re totally aware of that. DEVONthink has changed with such a pace, that it’s completely impossible to change the documentation with the same speed.

As we know that we should provide you with a better manual: it’s just in the works. DEVONthink Pro will come with a completely new documentation that is mainly a real documentation, explains every menu command, contextual menu item, every window gadget, etc. It will also have the usual installation instruction, system requirements and a version history. Besided that, we’ll take some parts from the older manual, namely useage scenarios, tips and tricks, troubleshooting, etc., and create a new tutorial from them.

But, this takes a lot of time, especially for a small company like ours. So, just stay tuned. The next beta of DEVONthink Pro will already come with the first chapter or so of the documentation to give you a rough idea where we’re heading.

Best,

Eric.

cool.

i well realize that it’s a big challenge to keep user doc current when the core app is moving forward quickly. I’m just glad you guys are aware of the disconnect, and hope you appreciate how important user doc can be for an app like yours. It’s easy to start using it and begin skimming the surface of features, but getting into more complex usage scenarios is not easy with this app without assistance.

the other thing I’d REALLY encourage you to devote resources to is restructuring your web page to be less feature-centric and more solutions-centric. Show how people can use DT/DA to solve problems and overcome challenges and put that information front and center. One has to really work to figure out what the heck DT does and how it can be helpful. Honestly, the only reason I gave it a second try was my intuition was telling me there was more here than I was picking up from the website. And that was indeed the case.

Show how students, engineers, artists, small business owners, tech geeks and others can use your fine products to make their lives easier.

If you do this, I guarantee you’ll increase your ratio of buyers to lookers. And I WANT you guys to be very successful so you are around a long time kicking out great apps.

There are applications you love, applications that leave you indifferent, and applications that you definitely don’t love. For me, DT is neither of these. For me, DT is an application I’d love to love. I bought DT, I bought DA, and yet I can’t say yet I love them, nor that I use them very frequently. And the reason, the only reason for this is the totally insufficient documentation that comes with these applications. I’m happy to read that’s going to change now. But I sincerely do hope it will be a fundamental and a permanent change.

By the way: would it be an idea to create a new section in the forum, dedicated exclusively to observations and suggestions pertaining to Devon’s manuals? Perhaps such a section would make this task of the Devon team somewhat easier.

This is also already on our to-do list. We have begun to make the product pages of DEVONthink more user-friendly, and will continue with making it more solution-centric. Agreed.

Best,

Eric.

Sure, the manual as you know it will be completely replaced.

As, as stated above, the actual manual will be discarded, this doesn’t make sense from my point of view. People will make tons of comments regarding the current manual which will only be updated a little bit until the next generation manual is here.

Best,

Eric.

Good news! I can’t wait to see the new manual(s)!