As the ‘moaner-in-chief’ on this topic, on this forum, and as someone who was not previously invested enough, I have to say that I support the assertion: “You have to be invested”.
I chose to migrate from Lr to dt after a year of more of comparative analysis (which, btw, quite vehemently excluded darktable at the start). Having reached what I regard as the best solution for me, being reasonably skilled in Lr, I then expected to spend a week or two in the migration - i.e. I did not invest enough in learning the basics of dt, let alone the principles of light behind so much of what dt does. I learned my lesson the hard and long way - the length of the migration reflecting my basic understanding as much as anything else.
This doesn’t stop me moaning about the ‘impenetrability’ of the user manual, though. Having read the intriguing and much valued set of comments that have followed from my post, I accept that there is much more I could (and should) have done to help myself, while maintaining my view that a user manual crafted for my level of ability is required, if only to accelerate the progress of others who decide to migrate to dt.
One key point that came ou there again, is that the official documentation is mostly a reference for the program, not a tutorial. As such, it can’t go into all the interactions between the modules, and shouldn’t spend too much space on the “why” of the different design decisions.
Also, what happened is that dt went through a change of paradigm, from display-referred to scene-referred, and both still co-exist. That makes understanding the program even more complicated, unless you realise what’s going on here, where the two paradigms differ and how that impacts the workflow (*).
So to understand that, you need extra information, but (IMHO) it’s not something to handle in depth in the manual. It should be mentioned (it is) but the manual is not the place to spell out all the consequences and pitfalls, especially not when dt is still ichanging regarding the scene-referred workflow.
(*)As an exemple (over-simplified): in scene-referred, you can mostly do whatever you want without paying attention to any clipping. That will be taken care of at the end of the pipeline, with the transition to display-referred (filmic). In display-referred, that attitude would probably lead to quick clipping of hightlights and loss of detail there…
Although I sympathize, I cannot agree with you. Manuals as in “fully detailed step-by-step manuals” have been on the way out ever since the beginning of the century. New printers, flatscreen TV’s, coffeemakers, electrical DIY stuf…they all come with mostly a “Quick setup guide” with the least amount of text and a few schematics. A bit like an IKEA assembly instruction.
Nowadays, stuff tends to come with a QR code which you can scan and will take you to a website with short howto videos or straight to Youtube.
So yes, if you still want a printed manual you’ll probably have to write it youself. I, as a DT user, have found the Youtube tutorials invaluable to learn my way around so to speak. I suppose there aren’t too many people around who want a printed manual or a group of them would have produced one online or as a downloadable eBook by now.
I would say one obvious difference remains that DT is not a commercial project with a target audience that must be serviced . It is a set of technical tools written and delivered by volunteers based mostly on their own interests and availability.
Commercial projects being so much broader in scope have a lot more potential and motivation for literature created by others also geared at making money and finding a target audience to provide that income.
I’m sure someone will write a beginner guide to DT or DT for dummies if they can sell x number of copies…or if we are lucky enough for someone to have unlimited time on their hands and the willingness to do so…
@priort We are also talking about two different kinds of documentation:
the official manual devised and maintained with the program, and as such under the responsability of the development team.
extra documentation written by third parties, where the development team has no say in (and no responsability for) the contents.
I think most of the books explaining commercial programs fall in the second category, i.e. are not under the responsability of the program owner. There’s little or no “how-to” documentation directly from the program or equipment maker (those downloadable manuals are mostly of the reference variety: “you have these buttons; they do x”). In addition, for hardware, they have to provide documentation in the language(s) of the area where the product is sold. That can be a significant burden in itself…
One of the things I really like about DT is that the buttons and check boxes are usually not a simple one-word selection. They are more often several very helpful words that really get me close to understanding as well as the helpful hover popups. In my opinion much better done in DT than hardly any other technical program I have used.
the official manual devised and maintained with the program, and as such under the responsibility of the development team. Which regardless of how you look at the DT manual is one of the best open-source manuals I have seen (seriously it is really helpful and awesome considering the price - in other words worthy enough to pay for).
extra documentation written by third parties, where the development team has no say in (and no responsibility for) the contents. I could not agree more. I would write it myself but I have no confidence I am doing it the right way…
I think that’s exactly the problem of the “extra documentation”:
developers don’t want to judge subjective how to guides
users are not sure if what they say is correct
That’s why I still think a wiki on darktable .org would be the best solution:
Users could start writing their subjective how-tos, and developers (or other users) could correct real mistakes or add their point of view.
.
I think to get users do the first step, it has to be as easy as posting on pixls to add how-tos.
As it’s no official documentation but a wiki, there is no need, that anyone approves pull-requests, but the crowd manages it for themselves.
Actually if you look at the commercial alternatives to darktable, lightroom, capture one, etc etc, their manuals are structured the same way as ours: a basic workflow section, then reference. The same for printer manuals (I used to write those too). This is the way product information is officially delivered.
Also note that we don’t have a huge team writing these. A whole crap load of the writing is done by @elstoc and I’ve tried to edit it and put the tooling in place to build all of it.
Thirdly, going down the road of writing more workflow stuff is a never ending task, because nobody uses darktable the same way, and everyone will want to feel special by having their way covered. Several people have come and opened issues, said they’d write a while bunch of stuff or even rearrange and rewrite the manual to make it better, but nobody has really followed through, because its a lot of work. And that’s just initially writing it. It has to be kept up to date as well.
I think the Darktable manual does a great job as a reference manual. But as any writer of documentation knows, there are different kinds of documentation, and the reference manual is only one of them. Other common variants are the Getting Started docs (Darktable has that, too), a Q and A, and Tutorials.
I think a set of tutorials would go a long way to help new users with specific topics, and eventually ease them into the reference manual.
I very much like the short, pointed video tutorials of Capture One. Usually just a few minutes of “how do I…?”. There are several of those available for Darktable as well, which could be linked in the manual.
Agree 100 percent the manual is the manual describing the basic options and what they do…Describing use cases and providing insight at varying levels of difficulty has to come from the community of users and there are many offering their time and experience to our benefit producing written and video content…something like that cannot be captured in a one size fits all manual… Like anything new and technical the rewards will be proportional to the time and motivation invested to realize a degree of competence and this will come easier to some than others
I agree, but although I love the videos of Bruce, Boris und Nicholas, it happens that there are mistakes, or things change, so in both cases it’s much easier to correct a wiki than redoing a video.
When I studied to become a teacher one of the most important things I learnt was that we all potentially have different learning styles. I do not learn well by watching videos. I learn better from reading and experimenting. When I watch @anon41087856 videos I find them very informative and technical. But a 1.5 hour video was Aurelien is a full days work for me as I have to pause the video and experiment in Darktable to really understand the technique and concept he is teaching. I really appreciate his videos, but I also want to go to a written manual and get a good overview of the tool and then more detailed examples of how to best set the sliders and controls. This second part may best be done by users like ourselves adding to the manual with examples rather than expecting the developers to do all the hard lifting. I would love more written documentation or a wiki developed by the users. I would be happy to contribute if we could get this started.
There have been some threads like the let’s learn filmic together. There was a lot of great information shared there via discussion. Perhaps better targeted questions might help but this thread was great because it was spearheaded by Boris…others can move off topic quickly sometimes
