Its a static site and all content is markdown. Its easy to write, easy to contribute.
So what is the process?
- Create a new top level menu section for Tips, tricks and Howtos
Get approval to install on darktable.org
- Create a Markdown file containing Hints tips and howtos for a topic like “How do I enhance contrast in 3.6?”
Can you recommend a good markdown editor for Linux?
-
Submit the file to whoever is managing darktable.org for approval
-
Let everyone know the file is live, but can be edited/corrected by anyone
-
Profit . . .
Markdown is really simple, so a basic text editor should be fine. You can build the darktable.org site locally if you are on Linux (see the README page on the repo) to see the result of your efforts. If you really want a point-and-click interface you could use hackmd.io to generate the markdown.
I’d open an issue and be very specific about what you want to write. Don’t try and do the whole thing first, just start with one article.
You can clone the repo, and Hugo runs on all platforms of you want to build the site locally.
Again, please don’t make a bunch of changes, but rather open an issue and describe the article you’d like to write.
1 Like
I use Ghostwriter myself. It’s specialized, and easy to use. There is markdown cheat sheet and a preview window. All what is needed to render correct markdown 
Just make sure to check which exact version of markdown is used.
I’m learning CAD right now, and the two-punch approach I’ve relied on for decades is proving it’s worth: 1) a comprehensive reference manual, and 2) at least one “get-started” tutorial. If I’m staring at a slider wondering what it does, I want a reference where I can easily find that specific definition. But, getting started does require some sort of “story”; I left FreeCAD behind because I couldn’t find such oriented to my use case.
My hack software rawproc has a comprehensive reference in the help file, but no tutorial material. Probably why no one else is using it… With a bit of free time coming up I’ll be doing a video or two.
But my point is, both types of documentation are needed to both get started and then to master bit-by-bit as new situations arise. And, I’ve found with digital photography there’s an underlying knowledge base that’s needed, that of the digital imaging mechanism. Hard to wrangle a slider if you don’t understand the thing it’s working on…
1 Like
Don’t do that to the poor person! 
I’d at least suggest RawTherapee or ART which IMO are a bit more intuitive than darktable but aren’t throwing peolpe into Adobe’s gaping maw of mediocrity. Different tools for different users is just fine!
First, the Raw Photography tools - WOW did not know that channel existed! Second the work of the coders and writers for DT will never be appreciated enough!
As far as DT goes my mission for it was to replace Adobe period. Dt has succeeded 1000%. So I thought I could refer DT to my friends but was consistently told no without some extended hand holding. The reason given was 1) Where do I start and 2) Where do I find contrast, exposure, vibrance, etc. and on. Can I do what I want - yes. Can I do it better in DT - yes. Can I do it more accurately in DT -yes. How did I get there - Bruce, Rico, etc., and yes some of came from a well written manual. I have to admit I have a OneNote script I follow - but that is the price of admission to such an excellent piece of software. So, the question is DT for anyone trying to get out from under Adobe? I don’t think so unless you are willing to put in the time yourself to educate yourself. I think that is the price of admission to open source software as is occasionally buying Rico a cup of coffee. When people ask me what DT cost, I tell them only the time for them to sit down with me and go through at least one RAW photo.
I would reflect back and video, manual, more videos, this forum, more videos and manual again got me going. In other words all the above comments are very relevant and true.
As a side some of us felt confident and then Scene Referred threw a lot of us for a loop. I did have to wait for some videos to come out to get me back up to speed.
3 Likes
You hit the key point…you have to be invested… and while there may be frustration its half of the fun…
As the ‘moaner-in-chief’ on this topic, on this forum, and as someone who was not previously invested enough, I have to say that I support the assertion: “You have to be invested”.
I chose to migrate from Lr to dt after a year of more of comparative analysis (which, btw, quite vehemently excluded darktable at the start). Having reached what I regard as the best solution for me, being reasonably skilled in Lr, I then expected to spend a week or two in the migration - i.e. I did not invest enough in learning the basics of dt, let alone the principles of light behind so much of what dt does. I learned my lesson the hard and long way - the length of the migration reflecting my basic understanding as much as anything else.
This doesn’t stop me moaning about the ‘impenetrability’ of the user manual, though. Having read the intriguing and much valued set of comments that have followed from my post, I accept that there is much more I could (and should) have done to help myself, while maintaining my view that a user manual crafted for my level of ability is required, if only to accelerate the progress of others who decide to migrate to dt.
One key point that came ou there again, is that the official documentation is mostly a reference for the program, not a tutorial. As such, it can’t go into all the interactions between the modules, and shouldn’t spend too much space on the “why” of the different design decisions.
Also, what happened is that dt went through a change of paradigm, from display-referred to scene-referred, and both still co-exist. That makes understanding the program even more complicated, unless you realise what’s going on here, where the two paradigms differ and how that impacts the workflow (*).
So to understand that, you need extra information, but (IMHO) it’s not something to handle in depth in the manual. It should be mentioned (it is) but the manual is not the place to spell out all the consequences and pitfalls, especially not when dt is still ichanging regarding the scene-referred workflow.
(*)As an exemple (over-simplified): in scene-referred, you can mostly do whatever you want without paying attention to any clipping. That will be taken care of at the end of the pipeline, with the transition to display-referred (filmic). In display-referred, that attitude would probably lead to quick clipping of hightlights and loss of detail there…
Although I sympathize, I cannot agree with you. Manuals as in “fully detailed step-by-step manuals” have been on the way out ever since the beginning of the century. New printers, flatscreen TV’s, coffeemakers, electrical DIY stuf…they all come with mostly a “Quick setup guide” with the least amount of text and a few schematics. A bit like an IKEA assembly instruction.
Nowadays, stuff tends to come with a QR code which you can scan and will take you to a website with short howto videos or straight to Youtube.
So yes, if you still want a printed manual you’ll probably have to write it youself. I, as a DT user, have found the Youtube tutorials invaluable to learn my way around so to speak. I suppose there aren’t too many people around who want a printed manual or a group of them would have produced one online or as a downloadable eBook by now.
I would say one obvious difference remains that DT is not a commercial project with a target audience that must be serviced . It is a set of technical tools written and delivered by volunteers based mostly on their own interests and availability.
Commercial projects being so much broader in scope have a lot more potential and motivation for literature created by others also geared at making money and finding a target audience to provide that income.
I’m sure someone will write a beginner guide to DT or DT for dummies if they can sell x number of copies…or if we are lucky enough for someone to have unlimited time on their hands and the willingness to do so… 
1 Like
@priort We are also talking about two different kinds of documentation:
- the official manual devised and maintained with the program, and as such under the responsability of the development team.
- extra documentation written by third parties, where the development team has no say in (and no responsability for) the contents.
I think most of the books explaining commercial programs fall in the second category, i.e. are not under the responsability of the program owner. There’s little or no “how-to” documentation directly from the program or equipment maker (those downloadable manuals are mostly of the reference variety: “you have these buttons; they do x”). In addition, for hardware, they have to provide documentation in the language(s) of the area where the product is sold. That can be a significant burden in itself…
Three things:
- One of the things I really like about DT is that the buttons and check boxes are usually not a simple one-word selection. They are more often several very helpful words that really get me close to understanding as well as the helpful hover popups. In my opinion much better done in DT than hardly any other technical program I have used.
-
- the official manual devised and maintained with the program, and as such under the responsibility of the development team. Which regardless of how you look at the DT manual is one of the best open-source manuals I have seen (seriously it is really helpful and awesome considering the price - in other words worthy enough to pay for).
-
-
extra documentation written by third parties, where the development team has no say in (and no responsibility for) the contents. I could not agree more. I would write it myself but I have no confidence I am doing it the right way…
-
extra documentation written by third parties, where the development team has no say in (and no responsibility for) the contents. I could not agree more. I would write it myself but I have no confidence I am doing it the right way…
1 Like
.
I think that’s exactly the problem of the “extra documentation”:
- developers don’t want to judge subjective how to guides
- users are not sure if what they say is correct
That’s why I still think a wiki on darktable .org would be the best solution:
Users could start writing their subjective how-tos, and developers (or other users) could correct real mistakes or add their point of view.
.
I think to get users do the first step, it has to be as easy as posting on pixls to add how-tos.
As it’s no official documentation but a wiki, there is no need, that anyone approves pull-requests, but the crowd manages it for themselves.
Actually if you look at the commercial alternatives to darktable, lightroom, capture one, etc etc, their manuals are structured the same way as ours: a basic workflow section, then reference. The same for printer manuals (I used to write those too). This is the way product information is officially delivered.
Also note that we don’t have a huge team writing these. A whole crap load of the writing is done by @elstoc and I’ve tried to edit it and put the tooling in place to build all of it.
Thirdly, going down the road of writing more workflow stuff is a never ending task, because nobody uses darktable the same way, and everyone will want to feel special by having their way covered. Several people have come and opened issues, said they’d write a while bunch of stuff or even rearrange and rewrite the manual to make it better, but nobody has really followed through, because its a lot of work. And that’s just initially writing it. It has to be kept up to date as well.
3 Likes
I think the Darktable manual does a great job as a reference manual. But as any writer of documentation knows, there are different kinds of documentation, and the reference manual is only one of them. Other common variants are the Getting Started docs (Darktable has that, too), a Q and A, and Tutorials.
I think a set of tutorials would go a long way to help new users with specific topics, and eventually ease them into the reference manual.
I very much like the short, pointed video tutorials of Capture One. Usually just a few minutes of “how do I…?”. There are several of those available for Darktable as well, which could be linked in the manual.