darktable: Plea for simpler documentation (again)

This is a discussion forum, right? It says so on the label (somewhere, I’m told). So, in my inimitable, annoying style I want to discuss something, without fear of being excommunicated (factually, demonstrably, this is the most benign forum I have used since the world-wide-web came into existence. It is sustained by people who are (unlike me) invariably well-informed, positive and helpful, so any fear of excommunication is probably unfounded).

So, appropriately equipped, with my trusty lead filled chicken (expression freely plagiarised from Private Eye in the Idi Amin period (q.v.)), I shall proceed to beat the authors over the head, for today The Topic is (groan, not again) the darktable User Manual, but with a slightly sharper focus than my previous rants on the subject.

Now I want to make it plain that I regard this manual as, (in my considered and irrelevant opinion), one of the best I have (partially) read, for what is also an outstanding product. The chief defect, I find, of said manual is that its authors are, by examination, obviously extremely technically well informed, are of an intellectual capability far in excess of my own, are skilful crafters of documentation in a highly concise and pithy style which is dense with important information – and write for people like themselves.

Please, could I have a version which is written for somebody like me – running well towards the rear of the human race, if not even (to mix a metaphor) wearing the Lanterne Rouge, and desperately in need of a toilet break?

An example if I may: the section on parametric masks.

This occupies just over a page of A4, if it were printed (I guess), including screen shots and diagrams. I have read it (considerably more than partially) numerous times in its 3.2, 3.4 and 3.6 guises. It’s a measure of how little I was able to glean, from such a condensed explanation of such an important topic, that the YouTube videos by such great contributors as Aurelien, Bruce, Rico etc caused a step change in my understanding – from ignoramus to ‘pathetic’. Now recently we have been blessed by Nicholas’ ‘Dabble’ videos, with a 4 episode series on masking in general, the last of which was on parametric masking. It lasts about 35 minutes, or about 10 times longer than it takes me to read the manual – and has gifted me another step change in my understanding of this wonderful capability of darktable. I now consider myself at an ‘introductory’ level of understanding – after a recent 35 minutes of video and 3 to 4 hours of experimentation.

How can a one and a half page of the user manual hope to match that? (Yeah, I know the response is going to be … well, I’ll comment on that in a while).

But, without wishing to disparage these videos in any way, I still have unfulfilled wants for deeper explanation of parametric masking (drawn and combined masks are intended to be the subject of a later rant) that are just not fulfilled in the user manual. Some initial examples are:
• can I have a deeper explanation of ‘exclusive’ , ‘inclusive’ and their inverted equivalent combined masks, with worked examples, especially covering the topics of channel polarity and of the need to invert channel masks twice, for the ‘inclusive’ case, as suggested in the manual, please?
• Could it be confirmed that ‘exclusive’, ‘inclusive’ and their inversions apply to combined parametric masks as they do to combined drawn and parametric masks?
• Can I create a combined (inclusive) parametric mask using the same channel (e.g. luminance) but with settings for the darker parts of an image (ground) and lighter parts (sky), or should I be using 2 instances of a module, with a luminance channel parametric mask for each – or should I be using some other technique altogether?
• Can I have an explanation of how I can use a parametric mask created in one module, in another ? (I had toyed with this for over a year and given up, until I caught a glimpse, out of the corner of my eye, while comfortably numb, of the use of something called a raster mask – which sounds like something one would purchase in the mercifully-now-escaped colonies of the Caribbean Sea).
• Can I save a mask as a preset to use in another image? Does this make sense? Or is this covered by the ability to copy history between images?
• Where can I make best use of Jz channel masks? Right now this channel seems to give little opportunity for masking, when the image is viewed using the ‘C’ key option.
• When to use the output data sliders and when to use both input and output?
• A more informative explanation of the mask refinement and additional controls, for example by use of illustrated examples.

As should be obvious, with my limitations I am looking for a lot more guidance. Yeah, I know the response is going to be “that’s not the objective of the manual”, but, really, should I be dependant on the ‘gifts’ I get from the YouTube video creators or should I be expecting even more gifts from the, largely unthanked, manual authors?

Now that’s a whole other topic: what is the motivation to develop FOSS applications and how should I, as a selfish user, react when those applications don’t ring all my bells? On that last clause, I found myself feeling particularly guilty when reading a discussion (in another part of this forum) on the apparent reduction of momentum within the RawTherapee development team. The comments there were most sympathetic and reminded me again that behind all these magical FOSS products are real human beings with real stresses and strains in their lives, that are felt in a way the commercial world can brush off.

So, thank you, those of you who are gifted enough to be code developers – and manual authors. But can I have more, please? I can’t do it - I’m too old and lack the necessary skills and knowledge.

3 Likes

I find that the best way (for me…) to get a practical understanding of what a module does, is just to experiment. Same for using masks. Sure, that takes time. But so much depends on what kind of images you are working with, for what purpose you are editing them, and what your tastes are, that following any kind of tutorial only helps me to find some “tricks of the trade”, and to get a feel for what’s possible.

And if the masking gets too complicated, I either switch to a drawn mask, or several copies of the module in question. Sometimes it’s just not worth the time to create the required mask in the way I thought best…

And, acquiring skills and knowledge always takes time. And patience.

1 Like

I think you’ve answered your own question there.

yes, you can have this, if you start writing it. That’s how foss works - don’t expect others having a great value in providing stuff you don’t even try to provide yourself. And in opposite to learning the programming stuff, writing user documentation (and not reference documentation) is quite faster to achieve.
So define, what exactly you need - what are the questions you want to be answered and use this as an initial structure.
Then collect everything you find that can answer these questions (and there’s plenty of stuff in youtube tutorials, pixls.us posts etc.) in a place (e.g. github) where others also can check this, edit this … it’s just someone must feel a need and start doing the job…

for most developers the motivation is simple - i need something not yet there or properly implemented in a tool i want to use - and i’m able and allowed to contribute …

6 Likes

(excuse my totally unqualified and off topic response… but your style of writing i enjoyed very much. although my attention span did not allow me to read until the end…)

8 Likes

Let me pipe in from a different point of view.

I’ve a hard time reading the documentation because there’s no picture. I need print screens of the module with arrows to highlight what they are talking about.

I have a very wide screen: on the left side: the doc, on the right dt and I still get stuck/lost (on regular basis). Often, I don’t understand the explanations.

Note that English is not my 1st nor my 2nd language which may/could explain things…

Thanks

When I started DT a little over 3 years ago I did not understand many of the basic terms and concepts. I had to spend a lot of time alternating between videos and experimenting. You get a shot of a test chart and start playing with parametric masks. You simply try all the option using a predictable image and see what happens. Without this experimentation no manual or set of videos would have advanced my aptitude. Basically in DT you learn by doing…Your post contains a lot of good questions about masks but the answers are not in simple documentation rather just simply try and see what happens…if you get results you can’t explain the ask…slowly you get how it works…

1 Like

TL;DR
Im principle I am with you. But in written documentations something likes “masks” are difficult to explain. I am to explain that people actually read it (a major task!) - AND understand it. It’s very abstract.

I saw only the “Dabble” video #4 - and it’s really very good.

IMHO the “Team” should encourage videos for the docs. Not something picked from Youtube (there are many suitable ones though) but rather specially produced for the docs. I believe there would be plenty of volunteers.

Maybe with some guidelines about the length (< 10 Min) and a written subs file (so it’s easier to translate for non-English - youtube’s auto-translate from speech has too many errors).

IMHO videos do better than long text.

The answer was screamingly obvious, until I came to your final sentence:

Your age is not relevant. What skills and knowledge do you lack that prevent you from writing for people like you?

Sure, but most modules have too many variants/options. You have different color spaces, then input/output, blend modes. Some “tricks” I see here I would probably not stumbled on myself in a lifetime.

1 Like

Sometimes it is also a case of you must learn to walk before you can run. Many users do not really even understand what a raw file is or all of the nuance of editing digital files/images, various file formats and basic concepts. IMO these cannot be skipped and will significantly improve the general understanding of what a module does. You can see it from the questions that many people ask, that they have the cart before the horse and are struggling because of it…

Some of this knowledge must also come from a desire to understand the basics. You won’t just see two videos and magically understand the software. Some module are almost an application all by themselves. Lets face it you are using a tool based on math and much of that math is not going to be hidden from you but is there to allow for absolute control…I don’t think anyone would go out of their way to make it difficult but at the same time this is not a phone app and there is simply and inherent level of complexity.

One last point would be that asking for simple is a bit like asking for intuitive (Aurelian’s favorite word). Define it. What I might find the most clear and pragmatic approach will be nonsense to someone else.

I think the best approach is if you have a variety of content from a variety of creators at various levels then users should be able to find one that communicates the level of information that they are looking for in a manner that they identify and connect with. Perhaps if there are ways to promote DT content and enhance pooling this information beyond what can be done here on this website (although I think it is one of the best forums with a great set of tools to share information) some efforts could be directed at that.

Just as we are lucky when someone is willing to share their tremendous skills and passion to create or adapt a module for the software we are also lucky when they create content…

As for simple…

There is a content provider that has meticulously gone through the entire darktable UI and module list, slider by slider, referring to the manual and sprinkled with examples… the channel is Darktable A-Z. I would say that the material there is presented in enough detail and at a slow enough pace that it should provide a clear simple frame work to use and experiment with most modules. I would consider it a good barometer. If those video’s cannot be followed and understood then there is a knowledge gap greater that what can be ascribed to DT.

https://www.youtube.com/channel/UC8CZCvZL3ic2hg074Quh2oA/videos

Beyond that you are only going to get proficient by repeated use and experimentation not from a manual or a video or two…maybe if the video gives you the confidence and direction to experiment that is the greatest contribution of all. In the end no matter what you do not everyone has the desire, patience and analytical approach to do the troubleshooting to learn software like Dt.

4 Likes

You could argue that the chief defect is that some people without the necessary technical grounding are trying to use a complex sophisticated tool for a task that they have not yet acquired the necessary background for…

All projects normally have or should have a mission statement. I suspect that the word simple would not be found in the DT mission statement if it exists… :slight_smile:

Perhaps that statement would be “Software made by the extremely technically well informed for the extremely technically well informed” all others (me included) proceed at your own risk :slight_smile:

2 Likes

Raster masks are what you want here.

I don’t think this makes sense. If you have literally the same frame, taken at a different time, just copy the parameters or copy the module history stack.

I find Jz to be very sensitive to dark tones, so good for changing tones in the shadows. I find the g channel better for mid tones or highlights.

You can likely forget the output mask, in fact its disabled in newer versions by default.


The manual is mostly reference material and only really helps one to understand once fascet of the application at a time. Putting it all together is left to the reader, mostly for the sake of maintainability and not to get caught in endless bikeshedding about the “right” way to do things.

The manual is not meant to be the end-all be-all for learning dark table, nor is it supposed to serve ever need of every user.

We do need video tutorials, forum posts, discussion, and other things to make a complete learning ecosystem.

8 Likes

Nicolas does strike a very nice balance and his personality and delivery are very welcoming…

I have a completely different view:

Of course you improve by doing and experimenting, but first you need a basic understanding what each slider is supposed to do.

If I want to just move sliders around until I like the result, I would use lightroom.

darktable is no intuitive one-slider-tool, but “Software made by the extremely technically well informed for the extremely technically well informed”

And that’s great, because it gives the power to the user.

But if it is not only meant to be usable by developers themselves, there has to be some way to get “well informed”.

In my opinion, written documentation is the best way to achieve this.

There already is an extraordinary ‘Overview’ section in dtdocs
(especially darktable 4.6 user manual - process)

And there even is a top-level section called ‘Guides & Tutorials’.

I would love to invest my time to extend those two sections:

  • add images where helpful for understanding
    (no complete screenshots which have to be translated / updated regularly)
  • split pages to ‘dummy’ sections on top and ‘expert’ areas below
  • add more written Guides & Tutorials

Is dtdocs the right place for this?

An alternative would be to set up a separate darktable-wiki, but I think there would be a lot of overlapping content.

1 Like

I would love to contribute some text and pictures to answer these questions, but there is a problem of how to consolidate the input from various people with various skill levels.

I can try to write a good summary of theory, techniques and examples, but inevitably I lack some detailed knowledge and need someone to QA my text and improve it. How do we bring such material to a publishable state? Personally I have lots of notes and Howtos that fit with my interest (bird and wildlife photography) but its not guaranteed to be accurate or useful to others.

Plus, the rapid advances in DT turn things upside down every 6 months.

So for me the question is how can we pool our expertise, time and writing ability to produce an up to date and useful Manual+++ ???

the main advantage of text compared to video is, that everybody can easily correct/improve/add the content.

So if there is a mistake, someone else can fix it.
If something changes in a new release, it can be adopted.

1 Like

There’s a difference between describing how the functionality of the application works and recommending techniques for image processing.

IMO (with the exception of the overview and some module-specific recommendations from the developers) the manual should be the place for an objective description of how the application works and nothing more. There are certainly places where the explanation can be somewhat opaque and the user manual is, for that reason, very much a work in progress. We welcome suggestions for how we can better explain the functionality so that it is more widely understood. Remember though that many of us have been hip-deep in this software for years, which makes it harder to know how best to explain it to less experienced users.

Because there are many ways to achieve a given result using the software, advice about technique and more specific “how to” guides are always going to involve someone expressing an opinion about what is “best” and will be subjective in nature. This is not something I (as the primary maintainer of the documentation) feel the least bit qualified to express an opinion on. This leaves me in a quandry if someone suggests a user manual update that I cannot objectively confirm to be true or not.

As such, while I agree that detailed “how to” guides are very useful to have, I’m not convinced that the user manual is the right place for it.

For other software this is the realm of “dead tree” books. Search Amazon for Lightroom books and you will find many many titles, most of them giving a particular photographer’s take on how to achieve the best results with Lightroom. Unfortunately open source is not so well served in this regard. So the options are videos, articles and posts on pixls or blog posts on darktable.org (I’m sure there are other possibilities as well).

3 Likes

It’s not one or the other, you want both. Detailed text, and a slimmed down video.

For example, somebody posted that 3.8 process link. Here the image processing in 3 modules could have a 90 Second video - created by “somebody” (quite a lot people do videos). Key is short.

As a guy who does long videos, I find that they get deprecated quicker and quicker.

On the topic here, I think it’s not a simpler doc that you want, but some sort of academy with seminars and real people in front of you. There is only so much we can do in self-teaching resources, and again, a manual is not a handbook.

3 Likes