I have many thoughts regarding what a new user’s experience might be and the darktable manual. Nothing below is a rant, but hopefully you do get a this-dude-is-frustrated vibe from the following.
Which version of the manual? It’s one thing to tell someone to “read the manual,” and give them a link to the “correct” or “current” version (are those even the same things?) and it’s another thing for someone to do a web search, find “the” manual, then claim, “Yes, I have read the manual,” and come to find out, they read version 3.8 of the manual.
Darktable itself lists 7 versions on their official website: resources | darktable
Any of those versions can be stumbled across in doing a regular web search. A savvy reader will notice at the top that the manual version is 3.8, realize they downloaded darktable version 5.4, and figure, “ah, this is the wrong manual, I need version 5.4,” and then spend countless time trying to figure out where the hell manual 5.4 is. And then (hopefully) eventually stumble across resources | darktable and see that version 5.2 is the newest. So they click on that, and…it doesn’t give the version at the top…“Well, hopefully this is the right version.”
One would assume that something as simple as dt’s screen layout, which basically hasn’t changed in, well, forever, would be explained in an easy-to-find place. Like here: darktable user manual - screen layout
The top panel and filmstrip/timeline parts of the screen have links so the user can find out more about that part of the UI. But if they want to know what the bottom panel is all about, they have to find that information by going to the menu, expanding either “lighttable” or “darkroom” then clicking on view layout. It would take 2 minutes to add those two links to the section “bottom panel” on the original “screen layout” page.
If a new user finds documentation about a module, many times they are confused because of the technical writing and jargon. I understand the need for precision when explaining something, but when it takes a new user multiple times of reading, doing additional research to determine what some of the jargon might mean, and then still coming here to the forum to ask WTF does ___ mean? you know there’s room for improvement in the writing.
I taught writing to 13-15 year-olds for 30+ years. Granted, that’s not necessarily the demographic darktable is probably used by, but a manual meant for new users should definitely be targeted for that reading level (and, in case you think that is “dumbing down,” a typical 15 year old can read at a fairly high level).
One of the pros/cons (depending on your technical knowledge or darktable user skills) that often gets mentioned concerning darktable is how great it is that nothing is “hidden” from the user—other software you simply move a slider and magically your image’s sharpness increases and another slider and the contrast decreases.
For users coming from such software, they need, at the very least, as @hannoschwalm suggests, “…a “FAQ/First steps” part at the very top of the manual.”
That’s a great first step, however, I believe it’s been suggested before, but many of the module pages could be divided into few sections and yes, I understand this is a massive undertaking):
- basic information using basic language for what the module is/does
- when/why and possible when/why not to use the module
- a picture of the parts of the module and each parts function using basic language
- a deep dive/technical section for the math/physics types who need to know what exactly is going on under the hood
- information covering aspects of the former use of the module if it has changed over time - then all of the old manuals could just be deleted so web searches don’t stumble across the old manuals
Before someone says, “Well, what’s stopping you from doing that on the official documentation?” let me tell you about that. It’s not that easy. Sure, some people like to tell others that it’s easy to make changes to the manual, just getting started is overwhelming to some of us—at least three different times I have read through all of the documentation, looked at pages, etc. etc. Only to be daunted by the scope and intimidated by the process.
Could the manual be a wiki instead, and anyone can make edits, which of course have to be approved?
For me, it would simply be easier to write my own information than attempt to rework the existing handbook.
@raublekick has created a great resource with the darktable 5.4 - A Introductory Beginner Workflow and Interactive Walkthrough and @Qor is attempting to do the same with darktable.info – Mastering Darktable 5.4: Workflow, AgX & Shortcuts
There is definitely a need for something for new users when it comes to the manual.
[edited to expand on idea] For those who are concerned about a “competing” forum, is that along the same lines as being concerned about competing forks of darktable? In fact, many times when a user makes a suggestion about the software, the response is: fork it and make those changes. Yet somehow it’s a concern to make your own manual?
Can PIXLS.US be bettered for the new user’s experience? Sure. @raublekick included some great ideas.
I’ve noticed that many of us who engage in Play Raw do so because we enjoy it. But sometimes, when a user has a specific question about how to do something, some of us ignore what they are asking about and just give an edit. For example, I have the bad habit of providing a black and white edit even if they have a question about color…shame on me. So maybe we can be more focused with that?
When asking on the forum about whether some users are experiencing a certain issue, there can be radio silence—I believe I’ve had a couple of my posts completely ignored, not even a “Nope, mine isn’t doing that.”
Maybe a new post somewhere brainstorming some ideas?
With the increasing prices of other image editing software I think there is going to be a continual increase in new users. Let’s make the atmosphere welcoming.
Just my 2p.