Difference between manual and darktable.info site

[paperdigits (Mica)]

NOTE this was split from [DE] darktable.info – A new resource for the German-speaking community (Modern Workflow & AgX) - #206 by Qor

@Masterpiga

I will exemplify with an anecdote.

Here are some things that used to be true of the documentation but now is not:

You used to have to write markup like

<?xml version="1.0" encoding="UTF-8"?>
 <book xml:id="simple_book" xmlns="http://docbook.org/ns/docbook" version="5.0">
   <title>Very simple book</title>
   <chapter xml:id="chapter_1">
     <title>Chapter 1</title>
     <para>Hello world!</para>
     <para>I hope that your day is proceeding <emphasis>splendidly</emphasis>!</para>
   </chapter>
   <chapter xml:id="chapter_2">
     <title>Chapter 2</title>
     <para>Hello again, world!</para>
   </chapter>
 </book>

in order to contribute to the docs.

The docs used to only be available on a gitlab pages site because only a few people could build them

The docs were still out of date when using XML because writing XML by hand is cumbersome.

Since there was little tooling around it, it’d often break

Reviewing contributions was a burden because markup was so heavy.

We’re still failing in the same basic ways that we were back then: the words on the page are not keeping up with the application itself. We are hesitant to add more features to the docs project because the failure is so basic. Putting more technical things onto of the project will lead to more failure, not less failure.

If we put in <details>, why not put in some other HTML? Why not author the whole thing in HTML?

We went for perhaps the simplest thing we could to try and set the bar as low as possible for people to write the words that are missing.

By far, the most limiting thing for all users of darktable is that the manual isn’t up to date.

@Masterpiga

It also suggests that the technical needs of the maintenance of the documentation take precedence over other considerations.

It certainly does, given the history of the project. Markdown gives us a relatively straight forward path to PDF and Epub as well. People can learn markdown easily. The technical overhead to build the site is relatively little compared to what it used to be and the format is neutral enough that we can switch tooling if we needed to.

@siamak

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.

Been there, done that. Not happening. We’ve asked, begged, pleaded, cried, and stomped our feet about it. That idea was rejected. And that happens. You need a certain amount of humility to participate in a mature open source projects.

@Qor

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.

This is a prime example is splitting up resources that are extremely limited.

@Qor

That’s also a very good idea. Perhaps the darktable logo could be used as an icon. Shouldn’t be a problem? @paperdigits

That’s fine.

[paperdigits (Mica)]

Hopefully my last post to this thread:

If the general community feeling is that we’re really doing this bad of a job on the docs, darktable.org website, and in this community, I’m more than happy to step down from all of them and cede way for someone else.

[Qor (Chris)]

@paperdigits

That’s fine.

Thank you!

@paperdigits

If the general community feeling is that we’re really doing this bad of a job on the docs, darktable.org website, and in this community, I’m more than happy to step down from all of them and cede way for someone else.

It took me a while to understand the manual, but now I think it’s really brilliant, especially if you want to read up on the details.

When it comes to dealing with the community, I don’t think there’s anyone who would complain about you.

[bastibe (Bastian Bechtold)]

@paperdigits

If the general community feeling is that we’re really doing this bad of a job on the docs, darktable.org website, and in this community, I’m more than happy to step down from all of them and cede way for someone else.

I don’t think we are saying that at all. Absolutely not. The docs remain, without a doubt, the definitive source of truth for all things darktable.

Some people apparently feel that there should be an additional resource specifically catering to beginners. I for one will let them do their thing.

But, as for myself, I’d rather invest what limited effort I can spare to this forum and, if I ever get to it, the official docs.

[Masterpiga (Daniele Pighin)]

@paperdigits

If we put in <details>, why not put in some other HTML? Why not author the whole thing in HTML?

I understand that it’s a slippery slope, and in my post I also clearly stated that I understand why the proposal was pushed back against. It was not a criticism, but rather a data point. Pure Markdown is one constraint that we have to keep in mind.

@paperdigits

If the general community feeling is that we’re really doing this bad of a job on the docs, darktable.org website, and in this community, I’m more than happy to step down from all of them and cede way for someone else.

I don’t think this has ever been suggested or implied.

The docs in their current form serve one purpose very well.

The question is whether the community feels that they would benefit from being also something else, and if yes to what extent, or whether it’s okay to leave this role to other channels which already exist (e.g., youtube videos, @garibaldi’s tutorials and now also darktable.info).

My personal opinion, as I elaborated in another post, is that we could consider restructuring the contents of the most technical sections (i…e, the processing modules) so that they would introduce complexity more gradually.

The schema could be something along these lines: a brief overview to set expectations, a couple of usage examples with before/after figures for different presets, best practices and pitfalls, controls overview and full technical docs. With proper captioning and a predictable layout we can go a long way towards guiding the users to find what they need more quickly.

That said, this is not necessary. It is perfectly fine if users start their journey from another resource and use the official docs mostly (or exclusively) as a technical reference.

[Doug-Phoenix (Douglas Webb)]

Mica,

Please, no, we value your good work here, and your persistence and patience. This is a great resource for everyone.

As I indicated earlier, I have always felt welcome here and I have learned so much by participating in the forum. I hope to be able to lend a hand with the docs once I feel qualified.

I think it’s great that there are some written guides for beginners, to supplement some excellent video tutorials. The recent tutorials by Andrew Raub, “Avid Andrew,” and the one at .info are welcome.

And while I fear that another forum may prove to divide the community, it seems that a .info forum is here to stay, despite what I think about it. So let’s continue here and keep things improving.

Again, you are valued and your good work here is appreciated.

That’s it from me; my last post in this thread.

[Macchiato17 (Lars Fiedler)]

Dear @paperdigits,

@Doug-Phoenix

As I indicated earlier, I have always felt welcome here and I have learned so much by participating in the forum.

This is also my experience here, and I really would like to encourage you to not step down. I see all this struggling reflecting in this thread, indicating a strong binding of the arguing people to me. And I feel the energy you put into moderation and maintenance of this forum an site. So I deeply appreciate this and I think that it is simply good to have you here.

So yes

@Doug-Phoenix

So let’s continue here and keep things improving.

I also would like to second this.

All the best,
Lars.

[paperdigits (Mica)]

Do not need/want an ego stroke. Do want to be productive. Do not want to re-litigate choices that are already made and aren’t changing. Would like the benefit of the doubt that we have some idea of what we’re doing at this point.

[siamak]

@paperdigits

We’ve asked, begged, pleaded, cried, and stomped our feet about it. That idea was rejected.

I did not know that and that maybe is the root problem. Giving responsibility without authority. There’s a period shortly prior to new release that is called maybe “feature lock” that no one can add anything so developers can get the DT ready for release no matter is liked or not. I do not know about DT organization of responsibilities. Here also must be enough authority for document writers like you to issue such demand and everyone must obey it.

I totally sympathize with you putting you in a such difficult position.
Can you imagine a product such as a car or even a camera sold without a current manual?
People who put the document together if not more but as critical as feature and code developers.

[paperdigits (Mica)]

@siamak

Here also must be enough authority for document writers like you to issue such demand and everyone must obey it.

I wish that were true, but it isn’t.

@siamak

Can you imagine a product such as a car or even a camera sold without a current manual?

No. And I put together manuals for cars for a living.

[Macchiato17 (Lars Fiedler)]

Would it make sense, if I try to condense it as follows (there are two platforms, the official and the .info. I would like to focus on the official site to improve here):

• the documents of the manual are partly outdated, some modules currently have no documentation at all
• there have been several suggestions for improvements to make the “onboarding” easier, e.g. by having an introduction / abstract as the first paragraph of a document, then the light-weight part and a deep-dive for those who want it hard™

For sure I don’t have an overview, but it should be possible to sort things out and derive concrete steps from this thread to improve step by step (which I think might be feasible). Don’t know if I’m completely “off”, but would it be helpful to build up a backlog e.g. in the doc repo by

1. prioritizing which chapters most urgently need
   • an initial version, because they are completely missing
   • an update to reflect the current implementation
   • other improvements
2. prioritize, which chapters should get the “make onboarding easier” refreshment suggested here
3. set up some guidelines describing the goal of the “refreshment” (to keep everything within the same “style”).
4. sorting out perhaps still existing technical hurdles in the process of doc contribution

Or is it a “been there done that” already and there is just nobody having enough spare time to contribute to this part? I’m still trying to figure out, how my contribution may look like in this context

[paperdigits (Mica)]

Thanks for the summary @Macchiato17

For me, the answer to the question “what is the difference between the first three sections of the manual and the darktable.info information” would need an answer. So far, the answer is “screenshots” and “quick start.” That answer doesn’t feel very thorough.

So I think the first step is understand what exactly the gap is in pretty great detail.

[martinus]

@paperdigits

For me, the answer to the question “what is the difference between the first three sections of the manual and the darktable.info information” would need an answer. So far, the answer is “screenshots” and “quick start.” That answer doesn’t feel very thorough.

I would say, checkout the darkroom section of the .info. There is - if you ask me - the biggest difference with manual. There is information on bunch of modules that is much more compact, more visual and much ‘how wot’ based. As an example see: AgX - Mastering DT 5.4: Workflow, Shortcuts, Themes & AgX or another example: Color Balance RGB - Mastering DT 5.4: Workflow, Shortcuts, Themes & AgX

Or is this not what you mean? (I could interpret your message in multiple ways)

[paperdigits (Mica)]

@martinus

Or is this not what you mean? (I could interpret your message in multiple ways)

To me the pages you linked look more like the module reference section, which is not in the first 3 sections of the manual, its is much later.

I haven’t seen any answer that indicates that anyone has actually looked at the first 3 sections of the manual, but maybe that’s just me.

[martinus]

@paperdigits

For me, the answer to the question “what is the difference between the first three sections of the manual and the darktable.info information” would need an answer. So far, the answer is “screenshots” and “quick start.” That answer doesn’t feel very thorough.

So I think the first step is understand what exactly the gap is in pretty great detail.

I don’t think that the gap is so much in the ‘first three sections’ of the manual. Actually, for me the interface of darktable was pretty self-explanatory. That is not the part of learning darktable. Those sections are relatively close to Lightroom and other software. And yes, I have been through the first 3 sections of the manual and compared it with the .info site. It is more visual and a bit more step based, and maybe the wording is - in my perspective - a bit easier.

The difficulty of darktable is in:

1. You have to create your own workflow rather than opinionated flow.
2. The complexity of several of the models.

And that is where the .info is very different from the manual. But not in understand the overall interface itself

[Qor (Chris)]

These are the headings of the first three chapters. Which of these are important for beginners?
As I already mentioned, I think a signpost (Wegweiser in German) (for beginners) is missing.

[paperdigits (Mica)]

@Qor

These are the headings of the first three chapters. Which of these are important for beginners?
As I already mentioned, I think a signpost (Wegweiser in German) (for beginners) is missing.

This is starting to feel like bad faith engagement.

Are you actually interested in collaboration? Or just in promoting your own thing? Promoting your own thing is fine, but please don’t waste my time if you can’t engage in good faith.

I’ve asked quite a few questions in good faith to try and figure out exactly what the gap in the information is, but they don’t seem to be answered.

Do you disagree with trying to find the gap in the existing docs? What is going on that I only get these kinds of response?

Honestly, this is extremely frustrating.

[Qor (Chris)]

@paperdigits

This is starting to feel like bad faith engagement.

Are you actually interested in collaboration? Or just in promoting your own thing? Promoting your own thing is fine, but please don’t waste my time if you can’t engage in good faith.

I’ve asked quite a few questions in good faith to try and figure out exactly what the gap in the information is, but they don’t seem to be answered.

Do you disagree with trying to find the gap in the existing docs? What is going on that I only get these kinds of response?

Honestly, this is extremely frustrating.

Actually, I’m trying to help you understand the difference. It’s also frustrating for me to see how my efforts are being received by you.
None of your assumptions are true; I’m REALLY trying to help.

[martinus]

@paperdigits

I’ve asked quite a few questions in good faith to try and figure out exactly what the gap in the information is, but they don’t seem to be answered.

What if it the other way around? The manual tries to be completed. But that can be overwhelming for new users (it certainly was for me). But the .info is more concise and more tailored towards beginners. If there if an information gap, it is at the .info site But I think they did that on purpose. Not all the information in the three first sections is needed when you start with darktable. Or do you think different @paperdigits ?

[Qor (Chris)]

@Qor

As already mentioned, we try to keep the content as concise as possible (for starters) in order to use the limited resource of concentration as effectively as possible. In other areas, we will then go into more detail.

You ask what the difference is. What I have already written here and what I tried to clarify with my question about the screenshots.