A great guide would be one like this with tips and workflow to demonstrate the manipulation of elements like this in the photo…but this is time consuming and really is the work of the user and and not the developer…The 10 Elements of Composition in Photography
This is a good link, but all of that has nothing to do with darktable or post processing in general, save the crop tool. The darktable user manual is about using darktable and doesn’t and won’t cover how to be an adequate photographer.
Similarly, we can’t provide you with the skills to visualize your own work in post, we can only provide the tools.
Visualization is hard at first, but you need to break it down into steps. Look at your raw and ask yourself, what adjustment should I make? First one is probably global brightness. Follow by global contrast, etc etc.
Once you can describe what you want to do to your images in plain photographic language, then we can start to map those steps onto dartable’s tools.
I bet we would have miles long tread about which method would be the most suitable for the highlight reconstruction of the candlelight, how to make white balance with a second instance of the color calibraiton module without blowing the skin color, eventually to consider other demoseicing method and even make your own color profile for the camera. 
6 Likes
Now that like Mastercard is “priceless” For sure even something modern…say in point 11 of this site…
can you image how many people would hit this with heavy dehaze and bump contrast or add a bunch of color…don’t get me wrong the great thing about digital age is there are so many possibilities…To be honest its hard not to do these things…I think maybe the #1 point of digital editing though should be restraint and or all things in moderation…
2 Likes
One of the things I most often miss in the Play Raw section: Context.
Not knowing anything about the scene and having to guess by looking at a RAW, which might or might not have been exposed correctly or have a white balance appropriate for that scene makes things a lot harder.
I am curious though if the “RAW” from the above shot from Barry Lyndon was posted and there would have been mentioned that this was shot with candlelight only and a f/0.7 lens, fully open (50mm depth of field or there about) if they would have come up with the soft orangey look that Kubric achieved. I’m sure that most people have never even seen a scene solely lighted by candles 
Having a (darktable) manual is nice and all and, optimally, there should be a setup as described by @CarVac in post #15, but all that is rather useless if you do not know how to approach your photography and/or can visualize what it is you want/need to do.
Likely I wasn’t clear. I was suggesting something like that would be a great resource (ie a book on photography that did reference back to LR) not that this is what the manual should be….In fact as you say the manual is not or cannot be the source of some key parts of the process which are in addition to pushing sliders
I think “frequency” relates to the functions on the image after a Fourier transform.
Mathematically speaking, Define a function by looking at how luminosity changes as your finger traces a line across the image,
Then take the Fourier transform to get a representation of your function as a sum of sine curves. You will find that sharp changes in your function relate to high frequency components of the transform.
Its not easy to state this explicitly without some maths formulae but this should be enough for those who want to understand the origin of the jargon.
I would say, the most important criterion is whether the photo appeals to you or not. If it appeals to you, then you look at what is appealing and try to highlight that. Then comes the second question whether you are able to do it. Are you skilled enough to pull it off. What elements play the role and in the end, how do you achieve that with the tools you have at your disposal.
Exactly!
This is a process with steps that always oscillate within this triad: Emotional impact, artistic skills and mastery of the tool.
If the first is missing, the highest you can achieve is average craftsmanship. The results become solid, but boring in the long run.
If the second and third are missing, the tool is suspected of being defective or inadequate. This can lead to the fact that one lets it be.
Or despair of oneself.
But, if there is enough motivation, then you slowly start to learn both. First, without great pretensions to take the time to learn the first steps in the use of tools. At the same time, you make the effort to master the rules of shaping and composition. Both are independent of each other and will merge in your own creative act.
It can be, for example, that you are interested in black and white photography, you have read a lot about it and know what makes a good black and white photo. So, when you learn to use the tool, you focus primarily on mastering only the aspects that are important for black and white photography. Or, conversely, you’ve learned just enough to get black-and-white photos with the tool, so you’re learning about what conditions and composition rules are important for good black-and-white photography.
So you gradually develop your skills and abilities with which you parallel master the tool and also the art of composition.
The most important thing to know here is that you can’t expect the people who make the tools to provide this learning process for you.
It’s like going to a music store, buying a guitar and expecting the manufacturer or salesperson to teach you how to make music with it.
I don’t think anyone will come up with such an idea. Interestingly, as far as darktable is concerned, exactly these expectations we have here.
7 Likes
True, but oftentimes the salespeople are also musicians and frequently have leads on where their customers can go to improve their skills. I think that’s what some people are trying to get at here on this site.
unless someone has the time and passion to write a book on color theory using DT throughout to highlight the marriage of instrument and theory then these questions will just keep coming
In my opinion dtcocs could become this book step by step.
There already are “real” books about darktable, but even with 200-300 pages they don’t go into detail concerning color theory, and the biggest problem of course is the up-to-dateness (having 2 dt releases per year at the moment).
Both is easier to handle in dtdocs, because you can link to external resources going deeper, and it’s much easier to continuously update markup compared to releasing new editions of a book twice a year.
The up-to-dateness is even a problem with videos (see Bruce Willilams’ great! newbie videos he had to redo - which are outdated again by now).
And there already is “great educational content” in dtcocs, but for me it’s often hard to find it.
So perhaps it would be a good start to define a new top-structure, so that it’s easier to see the gaps which should motivate all of us to fill them.
The main split for me is:
a) what does this button do (= “Module Reference”)
b) how can I … (everything else)
a) is the classic manual-style description, b) is the detailed explanation with examples.
Ideally there are links in both directions.
Here is a draft of such a new structure:
- get to know darktable
1.1 what is darktable
1.2 user interface
1.3 basic concepts (sidecar files, rightclick on slider, …) - functions
2.1 import images
2.2 structure images (culling, rating, tagging, filter, collect)
2.3 develop raw files (color calibration/white balance, filmic/basecurve, …)
2.4 correct images (crop & rotate, retouch, perspective correction, sharpen, denoise)
2.5 export images
2.6 print
2.7 tethering
2.8 map
2.9 slideshow - advanced techniques
3.1 masks
3.2 styles
3.3 multi-instances - get involved
4.1 report bugs (errors in the program)
4.2 test existing features and provide feedback
4.3 add documentation
4.4 translate dt to your own language
4.5 program new features - Module Reference (A-Z)
5.1 astrophoto denoise
5.2 base curve
…
I have no interest in writing or maintaining a book about color theory and photography. One of the major problems of the manual was that it wasn’t up to date for the release. While we have gotten wider contributions since converting to markdown, the bulk of the work is still being done by a few people. I don’t think it is wise to expand without having dedicated people to write and maintain.
Further, user manuals are about how to use something. Automotive usrr manuals don’t contain a thesis on the internal combustion engines, and your camera manual doesn’t include Adam’s The Negative.
If you take a look at some other photo software’s user manuals, you’ll see dtdocs is structured very similarly. This was not an accident.
I’d much rather people be explicit and, say “I find x to be deficient.” Then we can talk about how to address the specific thing.
Instead of making us guess by inferring things about your new structure vs the current one, why not just tell us in plain, simple language?
7 Likes
That’s why I posted here before opening an issue/pull request on github.
I am definitely willing to invest more time on dtdocs, and if there are several others I am sure we could expand the scope of the manual.
That’s true, but still I think it would be great to have it. I bought a book ‘the professional manual for Canon EOS 5D II’ (in german) which positions itself as replacement for the manufacturers manual and also includes step-by-step workshops using the camera.
So I really think it would be great to have the fusion of ‘Usage of the instrument and music theory’
I think dtdocs is great if you follow the help-link in darktable or if you know what you are looking for (search for tag and you find a great description even if the path “module-reference/utility-modules/shared/tagging/” is not quite obvious).
But if I buy a new camera or use a new software, I like to read a guide from beginning to end, because I don’t know yet what I have so search for.
That’s why I love the chapter ‘Overview’ which covers the main points you should know before using dt (what are sidecar files, how to import/structure/edit/export, …)
So my specific suggestion is to also move all other chapters except ‘Module Reference’ to the same ‘How to’-style structure
(e.g. lighttable / digital-asset-management / star ratings → functions / structure images / rating)
Basic how-tos are covered in Overview > Basic Workflow. We resist really in-depth how tos in the user manual because if we include one workflow, then we get to include them all (and people have wanted to contribute their workflow, even of its weird). We try to stick to what is technically correct in the manual, and keep it minimal to try and cover every single scenario, of which there are infinite.
I’d love to publish user workflows elsewhere, either on the main DT site or on the pixls blog, where I am a maintainer of both. But so far nobody has taken me up on that.
1 Like
Art before numbers. Thanks !
9 Likes
There are a lot of good ideas in this thread but I’d like to take some time to talk about the pracicalities of all of this in the context of the darktable user manual. While I’d love the user manual to be all things to all people and I welcome contributions, an important consideration here is the future maintenance of dtdocs. This is not the same as “writing content” but is about making sure that the content remains up-to-date and relevant as the software evolves. As the primary maintainer, it is my job to think about these things.
The old version of the user manual was out-of-date. Always. One of the reasons for this was the nature of the tools and skills required to maintain it – the toolset was difficult to set up and writing documentation was way too time-consuming. But at the same time, there was a reluctance from some of the developers to get involved in documentation, for many understandable reasons. I have to assume that this problem will be a long-term one – look at the list of dtdocs contributors and you can see that this is still a very small team.
The creation of dtdocs as a replacement for the old manual was intended to try to reduce some of these pain points, by moving to markdown as the authoring language but also by creating a more maintainable structure. The revised structure of the manual was carefully considered and I am not interested in supporting another restructure – it’s a time-consuming process and that time could be better spent improving the existing content.
It might be worth a short discussion of some of the key principles that were used when coming up with the revised structure. Some are about the user experience but they are as much about trying to make this project as easy to maintain as possible. These principles are a large part of the reason why the current development website is mostly up-to-date with the current state of development for version 3.6.
- It should be comprehensive – it should describe all of the functionality of the application.
- It should have a consistent and logical structure and every piece of functionality should have its own logical place within that structure. Satisfying points (1) and (2) is most easily achieved by having a structure that closely resembles the structure of the software itself.
- It should be as long as necessary but as short as possible. While it might seem counter-intuitive, over-long wordy descriptions are often harder to parse than short information-rich sentences. Brevity also makes translation easier.
- Partially linked to point (3), functionality should be explained once and only once. We don’t want every change to the software to result in a big documentation rewrite. The overview section is an exception, in order to give people a basic introduction to the software, but I don’t want to expand this more than necessary.
- Images should be included only where necessary to improve understanding of key principles. This is both a translation issue (we can’t translate images easily) and one of practicality. We don’t want to have to spend a lot of time redoing images, especially where those images are part of a larger workflow. For example, if the manual describes a 10 step process and someone makes a development change that impacts step 3, the maintainer should not have to redo all of the screenshots in such a guide.
- It should be objective. This is a description of software written primarily by the developers of that software. Any discussions about how to develop photographs are necessarily of a creative and subjective nature and will be interpreted by readers as a set of authoritative rules if provided by the darktable team. If developers start opining on these matters, the manual will quickly balloon in order to include more and more perspectives, workflows and opinions. There will be understandable disagreements on best practice and these will be hard to resolve. Maintenance and engagement will suffer.
In my opinion task-oriented (“how to”) content breaks most of these principles. It will rarely be comprehensive, requiring additional parallel documentation that includes more complete functional descriptions (duplication). It is usually much more verbose and harder to do without more images, and will probably include subjective and creative content.
That’s not to say that task-oriented content is a bad idea but the user manual is not the place for it. Here are some ideas on where such content does belong…
- YouTube videos
- Articles on pixls.us
- Conversations on discuss.pixls.us
- Blog posts on darktable.org
I’m more than happy to link to this sort of content from within the manual but I don’t really want to be responsible for maintaining it over the longer term. If we had a big marketing department behind us we might have an official magazine or something for this. But then we would also have an agreed corporate vision to push, rather than a disparate (and sometimes fly-by-night) group of developers all with their own valid and different opinions. Again, the darktable contributors page is instructive here.
This is the nature of open source and above all, practicality and pragmatism must take the lead here.
13 Likes
I agree, that being up-to-date is the top priority, and I really appreciate this!
I absolutely understand this, and if we don’t want to include task-oriented content, then it really does not make any sense to change the structure.
So there is one open questions for me:
What’s the best place and form for task-oriented content?
Videos have the disadvantage of getting old very quick
Conversations on discuss.pixls.us are very time-consuming to read through because they are (of course) unstructured.
So articles on pixls.us and blog posts on darktable .org would be possible.
But first of all, not everyone can provide content there.
And secondly there also should be some kind of structure, which does not exist yet.
So what about a wiki (for example the github wiki)?
I am a maintainer on both sites, so we can make space for tutorial content. Pixls.us already has tutorial.content, so there is already space there.
4 Likes
yes, but as said - not everybody can contribute there easily.
In a wiki everybody can add content instantly.
Maybe you could then copy single outstanding wiki-entries as article/blog to pixls/darktable.
1 Like