Let me piggyback this question to make a consideration: one clear advantage of doing anything outside of the official docs is that one is not limited in what can or cannot be done, which paves the way to being more effective.
I will exemplify with an anecdote.
In the past I had proposed to use some markup (e.g., <details>) to make the docs more easy on new users. People get demoralized if they feel that they have thousands of words to read just to learn how to use one module. Enabling users to discover complexity more gradually is something that I think would make the docs a bit less intimidating and more useful, as people could more quickly skim over most of the content to get a general idea instead of getting lost in the details.
I have been told that using markup is not possible, on the grounds that converting the manual to other formats and eventual migrations would be more complicated.
While this is a totally legitimate point, it highlights the fact that there are many limitations to what can be done to actually improve the docs.
It also suggests that the technical needs of the maintenance of the documentation take precedence over other considerations. I understand where this comes from, but it is indeed a very limiting factor.
Tutorial in form of blog, videos, etc can be used as quick start.
I rather have a manual that is as detail and complete as it can be. The ultimate guide. The issue, that I face sometimes is that manual is not up to date/current or some terms and concepts are that may need a further search elsewhere where can add to the confusion.
I do not know how resolve such issue. One possible solution that most probably will not be popular would be a policy of not releasing a new feature or change unless documentation for is reviewed and complete.
There’s a lot of good content on darktable.info. There are details on every page (that I’ve visited) that I don’t agree with, but overall it seems to contain good advice. That’s really a great achievement, this is shaping up to be a great resource!
However, as it is fairly opinionated, I find its authoritative tone problematic. One simple way to mitigate this would be the addition of links to the official manual, “for further details”. That way, darktable.info can stay opinionated and subjective (which is good!), but refer to the manual for the objective truth and full details. Mark the links with a little icon to differentiate them from internal links if you want to.
Our site thrives on feedback like this, and we are grateful for any comments you may have. One way to do this with little effort would be to mark the critical section in your browser and then send us a screenshot.
That is our goal for all pages (where possible). @EmerS has already implemented this for all pages in the “Darkroom” section of the EN pages, for example.
We have been “struggling” to keep up with him for weeks . What I mean to say is that this is also planned for all other languages, not just EN.
Individual pages of the DE version also have the corresponding link.
Anything that gets us on the golden path, our own “Secher Nbiw” (obscure Frank Herbert’s Dune quote) is very welcome. I’ve already learnt a lot and I’ve been using Darktable literally since the dark ages - or so it feels.
. What I mean to say is that this is also planned for all other languages, not just EN.