Re: [ibm-acpi-devel] [PATCH v5 2/6] leds: triggers: Add a keyboard backlight trigger

[Glenn Golden <gdg@zplane.com>]

Pali Rohár <pali.rohar@gmail.com> [2016-11-22 15:58:25 +0100]:
> On Monday 21 November 2016 14:29:00 Jacek Anaszewski wrote:
> > Let's wait until every involved part agrees (Pavel, Pali).
> 
> Ok, I read that discussion on linux-leds ML and finally understand
> motivation and results.
> 
> Personally I still do not like current approach and big problem what I
> see is that I was not able to understand *why* introduction of
> current_brightness is needed and how userspace application should use
> it, before I read whole that linux-leds discussion.
> 
> For people who already understand situation it is probably OK, but when
> I first time saw this patch series I just said WTF and description in
> Documentation files nor in commit messages did not help me.
> 
> I would suggest to properly document *current* behaviour of LED sysfs
> files in Documentation/ABI before doing any decision how to solve
> current problem.
> 
> Without correct documentation how sysfs LED interface behave in
> different situations (trigger is active; zero is written to brightness;
> brightness is read when blinking is active; etc) it is really hard to
> discuss about those problems. As many people (me included) first looked
> at those documentation files and think that info written here is correct
> and handle everything...
> 
 
+1 on the above sentiment, sense of frustration well expressed.

I went thru the same sequence of wtf-ing as Pali describes before coming
away with any level of real understanding.  IMO, this is a great example
of an issue which is 90% doc vs. 10% technical.

Hearing statements made earlier such as "the variable name doesn't matter
much" (approximate paraphrase) makes me worry, and must respectfully
disagree.  I am not involved at all in development or patches on this,
just a lowly Joe User type, and as such, can tell you that out here in
the cheap seats, the naming really does matter.

Please respect views of Pali as stated above and concentrate on documentation.

As an aside from complaining though: Major tip o' the hat to all the
motivated and devoted devs on this ACPI work throughout many years;
it's really very much appreciated, despite the occasional whining (as
mine above).