Documentation question: unclear on toggles

[xpe]

Toggles: [foo]

Use [foo] syntax to show or hide something based on a boolean expression foo.

This works on empty attributes:

From reading the documentation on toggles, it seems like it would control the rendering of an element. (In my experience, I don't recall seeing a 'toggle' feature in libraries along the lines of Maud; typically in other libraries I use conditional logic for this purpose.)

Or is it something else?

This issue suggests it is something else. (If so, the documentation's wording could be made clearer for sure.)

[puetzp]

The documentation states that this toggles attributes and classes on elements. It does not toggle the element itself with its respective attributes and elements. You are right that if you wanted to display an element on some conditional logic would use @if .

I have not been using maud for long, but I think the documentation is quite clear on that part.

[xpe]

To focus our attention on it, here is the current documentation:

Toggles: [foo]

Use [foo] syntax to show or hide something based on a boolean expression foo.

This works on empty attributes:

let allow_editing = true;
html! {
    p contenteditable[allow_editing] {
        "Edit me, I "
        em { "dare" }
        " you."
    }
}

And classes:

let cuteness = 95;
html! {
    p.cute[cuteness > 50] { "Squee!" }
}

[xpe]

'show or hide something'

To reiterate, it says "Use [foo] syntax to show or hide something based on a boolean expression foo."

Saying something is ambiguous. Does this mean an element? Seems like it could, maybe.

No? That's fine. But this would be extremely easy to clear up.

'toggles attributes and classes on elements'

@puetzp You wrote "The documentation states that this toggles attributes and classes on elements."

That's a nice summary. But, to be clear, no maud documentation I've seen says that verbatim. Did I miss it?

As you are not confused, you may not see it -- I refer you to my "Pay more attention to the confused" section below -- but there is a difference between your summary and the documentation in the place I showed. Small differences matter. It is good to welcome all improvements to documentation.

Feeling clearer months later is little consolation

I will grant that months later, yes, with the benefit of your one-line summary of the documentation, I feel clearer. But that shouldn't be the metric of success here. if someone has to step back and have someone else explain it, then it probably could have been clearer in the first place.

Clarification by saying what a feature does not do

Often documentation is made much better by saying what something does not do. A brief note along the lines of "To be clear, this toggling syntax does not pertain to elements / tags; only to attributes and classes.".

Thought process around documentation

The standards and thought process used for standalone documentation are not identical as writing document inside code, much less code itself. The goals and constraints are quite different. For example, the concepts of 'minimalism' and 'all code is debt' can have tremendous value when writing software. But extra clarity, even some degree of redundancy, serve very useful purposes in documentation.

Comparative expectations

Many templating engines do indeed have ways to toggle elements. I came to Maud looking for it. Like it or not, this becomes part of the user mindset when coming to Maud. It is wise to understand where people are coming from and respond accordingly.

Pay more attention to the confused

Generally speaking, when we hear differing opinions about documentation, we should weigh opinions both from people that think "it is good enough" and those who think it can improved. That said, I like to pay more attention to the confused people when writing documentation. That's how you make it better. Thank them -- think about all the people that won't give any feedback at all.

Why so long?

I have a philosophical bent -- meaning a love of knowledge and reasoning. I care relatively less if people agree with me on this particular issue. I'm more interesting in sharing what I've learned and learning from others. I've observed a lack of appreciation around the human aspects around software, so I speak up when I think I see that happening. It is getting better as more people notice it. (Yes, this is long, but I did organize it into headings.)

[puetzp]

Thank you for your thorough excourse on this topic. Since I (admittedly) do not have the same philosophical bent, I am going to take the easy route and basically agree with everything you are saying!

You are right in that it is vital for the documentation to highlight and explain unambiguously how a feature works. I also agree that the "toggling of attributes and classes on elements" feature is a prime example where precisely worded documentation is important since it is such a fundamental feature of this library and one that is, in my opinion, very well implemented and incredibly useful.

I understand that just because I do not have an issue interpreting the documentation does not necessarily mean that this is the case for everyone.

That being said I think a Pull Request that improves the explanation of this feature in the documentation will be more than welcome and appreciated by the maintainer(s)! And it will surely avoid confusion in future users who learn how to use maud as well.

[lambda-fairy]

Hi all, I haven't read the full discussion, but I'm happy to review a PR that improves the docs.

[puetzp]

Sorry, opened the PR in the wrong repository ... fixed.