https://www.khanacademy.org/math/differential-equations/laplace-transform
I know it is hard. This is college level math (I think 2-3 year).
1 Like
The issue with explaining diffuse/sharpen is that it is a general-purpose āsolverā (in the mathematical sense) which was originally written for edge diffusion only. If had only been used for that purpose then its interface, and the user manual, could have been simplified.
Fortunately for us, the developer then discovered that it could be used for a lot of other things as well, making it also a general-purpose module in a photo-processing sense, and meaning that none of its complexity could reasonably be hidden without reducing its usefulness. The large number of uses it has makes it virtually impossible to describe in a āvisualā way and means that all of the parameters need to be exposed and explained in a very general manner - something that is very hard to do without invoking the mathematics. In a lot of it I had to rely on the first draft and explanations of the developer and try to just make it as clear as I could.
Yes itās hard to understand, for me too. Fortunately the creator also provided us with a bunch of presets and some guidance as to how to tweak them, so Iāve never felt the need to understand it all in order to use it. Iām sure the developer discovered many of these things by trial-and-error with the algorithm as well.
The darktable documentation does not shy away from describing what a module does, in technical language, for those that can appreciate it. Thereās also something about being āopenā about the design and not ādumbing it downā too much which I personally like.
Where possible, we try also to make it clear what a parameter does and how to use it, from a user perspective. But we must acknowledge that this is not always easy/possible, since under the hood all of the modules are algorithms and many of their parameters are mathematical and physical in nature and hard to describe in a user friendly way without oversimplification. Even harder when the developer does not have English as their first language (and the user manual is English-first).
We are very open to discussing clearer wording if people can suggest something that is better (and still demonstrably correct) but this is very hard to do while also keeping the manual an objective and accurate description of how the software functions.
5 Likes
To loop this all the way back aroundā¦ Is DT really trying to appeal to a non-technical user (who wishes to remain nontechnical)? If a user is non technical but wants to learn, I think DT still holds up ok, and coming here and seeking help and community helps with this process (I hope???).
But if the user wishes to remain nontechnical, should we continue to expend effort to appease them? If yes where do we stop? Or do we keep going and actually just end up with āfree light roomā?
As a software developer myself, I can confidently say that software development would be a lot easier without the users 
I took a quick glance at the diffuse or sharpen module docs and I think thereās a few things that could be improved. The documentation starts off with defining what diffusion is, and thereās considerable technical documentation before it gets to workflow and suggesting to start with presets. Some possible improvements:
- Start with a general description of what the module does, similar to the docs for other modules. Something like: The diffuse or sharpen module can apply a variety of effects such as diffusion, blurring, local contrast, and sharpening. Included are a variety of presets which can be used to quickly and easily apply these effects.
- Next could be the āstarting with presetsā section
- Follow this with an āadvanced usageā section (i.e. the starting from scratch section) that sets the stage for the rest of the technical documentation that exists.
It might be nice for the modules to have a documentation template to follow so thereās a consistent layout and order of information. There could even be a table of contents on each page if the templating engine used allows anchor links within a page. I have some more general ideas too that Iād be happy to share.
2 Likes
thereās simply no technical writer in the darktable team. Writing user documentation isnāt something everyone can do - it needs a quite different language, not c or math.
So instead of moaning about inappropriate user documentation step in, spend effort to understand the math behind the modules and then write it down in a language an average user can understandā¦
Foss isnāt about demanding, but contributing
4 Likes
I disagree. I think @elstoc has done a fine job.
Iāve also put in a fair bit of work myself and tech docs is literally what I do as a profession.
However, itās become exhausting writing everything from scratch. The developers of new features donāt give us a clue what to expect in terms of usage and former devs left us a books worth of stuff to decipher. This is why there have been calls for help, this is why devs have been asked to write literally anything about the usage, but to no avail.
In terms of ideas of how to improve things there are lot of good ones, but they have to be put into action before theyāre meaningful.
5 Likes
Iām thinking of proposing that for 5.2.
6 Likes
Iām right here in this discussion. Can people stop suggesting Iām not up to it. Happy to hand over the reins to someone else. Volunteers?
We do try to use as consistent a format as possible, but sometimes such things can be overly restrictive for complex modules.
4 Likes
Yes it isā¦ However, the fact that by far the most titles in your search results are like āWhat is Bandingāā¦ I would argue that would non-technical user actually donāt knowā¦ and have to be educated 
Of course we can also argue if the DT manual page is the place to do that.
But I was also referring to the 32 floating point, etc.
But these technicalities asideā¦ How would people think as a first step to start linking to the explanation videos of @Bruce_Williams of the modules on the documentation of that specific module?
Iām not getting at anyone in particular.
Being the programmer for an application does mean that you will know the code, and what it does. But this can be a mixed blessing.
The difficulty is stepping back and seeing it from the viewpoint of the non-knowledgeable end-user. Making sure that one uses language that they will understand, rather than the language that the developer uses. Ensuring that steps are not missed out, because to the programmer they are obvious.
I see that @martinus is essentially making the same points.
A slight swerve, my wife sat on committees at a number of levels within the education community, developing subject curriculum specifications, looking at the implementation of the curriculum based on these specifications, checking examinations produced by exam boards and awarding bodies.
Eliminating lacunae and ambiguities in each of these stages, and ensuring that the language used was the same as that used by teachers was a major undertaking.
It is a difficult task, as is the production of good documentation.
Well, that takes me back a bit - Unix is user-friendly ā itās just choosy about who its friends are.
3 Likes
When I was in engineering school many years ago it was common belief even within the academic engineering community that technical types in general are not blessed with too many of the genes that make one proficient with some of the softer āliberal artsā such as diplomacy and writing in an engaging and coherent (to nontechnical types) manner. The way our brains are wired makes us too literal, too much directly to-the-point, and too prone to overlook and sometimes downplay the importance of critical details that are necessary for the nontechnical reader to comprehend nuances and implications of what the writer is trying to convey. Thatās why good technical writers are so rare and valuable.
dt is very complex for sure and the manual for it is great for those who already have some understanding of how the program works, but it is so long and so detailed and the program itself is so convoluted that beginners are always going to have problems knowing even what to look for in the manual.
1 Like
I agree, writing documentation is difficult.
But, do we actually need more documentation?
I get the feeling that the main problem is access to the available documentation:
- users have to find e.g. the manual and the various youtube channels;
- they need a way to avoid the bad documentation;
- and most importantly, users have to be willing to look for documentation.
For the first point, the manual is easy enough to find, the good youtube channels less so. Perhaps a page in the manual referring to good other sources could be useful?
But that still means users must be willing to look for answers other than posting a question in a forum.
Regarding complexity:
darktable is a complex program with a lot of possibilities.
Then again, modern cameras (esp.high end) arenāt simple either. And what Iāve seen of their manuals doesnāt impress meā¦ But, they can have a factory setting that allows anyone to take a decent picture of the more common kinds of scenesā¦ So who needs a manual?
But you would be totally wrong in that argument. The manual should absolutely not define jargon that is common in our niche. This is common practice in technical writing.
Then the user should start at the beginning. The manual has, like most other manuals, been designed this way.
2 Likes
Perhaps the āabbrā tag could be used where one wants to use a āuser-friendlyā term in the text, but the āabbrā tag could contain the technical term or description, possibly with the ādfnā tag if one is providing a definition.
Ah, the āAlice in Wonderlandā methodology:
" Begin at the beginning," the King said, very gravely, āand go on till you come to the end: then stop.ā
I was comparing with LR where the UI is organized around the āmaskā unit, so you have a list of masks representing different parts or subjects, and when you click one mask it opens a UI where you have all the modules and settings for this particular mask. So key points of this strategy are (in my opinion) :
- different masks are used to set different effects
- these masks related effects are grouped in a coherent UI unit
- the UI is not cluttered with the other modules (i.e.: you donāt have to look for/find all your mask-related modules in the UI)
So now I see two things when considering masking in darktable: the technical aspect and the usability aspect.
On the technical aspect there is no real debate, as you say, all of this is technically possible in darktable by using :
- new module instances
- re-use of masks as raster mask
- module names as proxy for masks name
I have no problem with this as this is my actual way of doing it in darktable.
On the usability aspect there are different things to consider. For basic editing this is fine because you will probably only have a few module instances. For more complex editing itās doable if you donāt have a lot of photos to edit. But the real limit for me if for edit sessions where you have many photos where you need a lot of masking (typical case would be (professional) wedding photography). In this last case, it is still doable, at the price of editing time.
I know this would be difficult to implement in dt and it would be justified only if a lot of dt users need it which Iām not sure.
But also we should not forget that paid/proprietary software products are targeted to professionals and productivity (maybe at the expense of scientific/correctedness), and they have tens of paid developers working full-time on it so we cannot really compare FOSS and proprietary. That being said, I should recognize that darktable fulfills its goals as a totally capable (at least technically) replacement for LR/proprietary software products.
1 Like
Ah, this is the difference between āa programmerā (I am a software engineer by trade) and āthe programmerā (I donāt do much if any coding on darktable except fairly simple UI stuff).
From the point-of-view of the documentation I try to take the descriptions I have from the developer and make them as simple and clear as I can (alongside trial-and-error playing with the functionality myself). Mostly the problem I have is getting complete descriptions from the developers. Sometimes (as in diffuse/sharpen) the problem is that even the descriptions from the developer are too complex for me (or that I donāt know how to translate them into easy text). When that happens, Iām left with trying to remove ambiguity and at least make it self-consistent.
Without input from the developer, itās very hard to be sure that what I write is factually accurate, let alone clear and understandable to the regular user (this also causes problems with accepting contributions from users that change meaning).
4 Likes
I guess you could raise a feature request. How about something like this:
- make all reusable masks (drawn and raster, or maybe just raster?) selectable on the mask manager
- allow the user to temporarily only see modules that use (or, in case of raster, define) that mask, for example on a new tab in the module group, or by adding a checkbox to the mask manager that is visible after selecting a mask: show only modules using the selected mask.
This would not address the desire to add new āeffectsā (modules) using the same mask, but maybe you can come up with a better design, or maybe this would also to improve your workflow, even in this form.
2 Likes
The Laplacian it is referring to is: Laplace operator - Wikipedia. Laplace transforms are something completely different entirely.
With that said I think some of the terms used in the documentation are technically dubious. For PDEās such as the heat equation, the first order term (divergence) represents advection, the second order term represents diffusion (Laplacian), and the third order term (of no interest to us) is dispersion. The module refers to both of the first two terms as diffusion (1st and 2nd order from my understanding of the code), and also has 3rd and 4th order terms. But, really, these two groups of terms (1st/2nd and 3rd/4th) are the same thing just applied to low and high frequency wavelets, respectively. Again, this is just my current understanding from the code.
Regards, Freddie.
1 Like