Ah, another former Saint-Petersburg resident. Hi there, Alexander!

Working on a retro-computer BLE/USB keyboard right now (HW&FW), with quality, low latency, and emulator/HW compatibility as the special sauce: https://twitter.com/spbnick/status/1546555198046457856

But then I got distracted into building a device for testing its latency:

https://github.com/spbnick/keypecker

https://twitter.com/spbnick/status/1645057450431635456

The FW is quite complete, but I only have one HW implementation :D

And then I got distracted trying to find a good way to acquire and retain the requisite deep BLE knowledge (already had some for USB), and drifted into exploring knowledge graphs as a means of processing and recording that knowledge.

Turned out all of knowledge graph databases are heavily front-loaded with schema development (and there are no actual GUI apps for them), whereas I have no idea what the schema will be, and would like to experiment with unconstrained data first. So I'm building a Python tool/library to allow free-form knowledge graph creation and schema inference, with data/schema export to some knowledge graph databases (like TypeDB or Stardog). I got to figuring out graph-building operators and expressions so far, and am making them work (the code probably doesn't make much sense):

https://github.com/spbnick/knob

An STM32-based business-card synth with touch-sensitive back-lighted keys. Got all the parts of the hardware more-or-less prototyped and working, but PCB layout difficulty (and my perfectionism) killed my interest for now:

https://twitter.com/spbnick/status/1340348572068360198

https://twitter.com/spbnick/status/1341507428131741698

An (integration) test framework for Bash (yeah, I know), written 10+ years ago to replace the one used by RH at the time (and to this day).

Repo: https://github.com/spbnick/epoxy

Slides: http://slides.com/spbnick/epoxy

Didn't stick, left QE shortly after.

Instead of using a faraday pouch to prevent this kind of attack, I added a kill switch to my key fob, a few years ago, and still use it: https://www.youtube.com/watch?v=02M57GPix-4

The problem is that manufacturers are using strength of signal to detect keyfob proximity, which is, of course, defeatable with a (somewhat expensive) amplifier.

I wonder how hard could it be to measure response latency instead? That should solve the problem.

I thought about selling those for a while (and got a few requests), but realized I can't easily design them for the many kinds of key fobs out there. I suppose the manufacturers are not adding them themselves because that would hurt the image of "security" of these key fobs.

Thank you for a thoughtful response. I'm a bit confused by your answer, though, because my problem was the lack of documentation, and making it easier for external contributors was an argument I was using, not the other way around. However, I think I see your points, and I would agree with them otherwise.

I experienced the problem first-hand, trying to add a feature to a complicated piece of code almost devoid of documentation, and spending a lot of time and energy on trying to hold everything in my head. Eventually I gave up and changed my approach, succeeding in the end, but documentation would have made it much easier, in my opinion.

I approached the team suggesting a few measures we could implement, with increasing levels of effort, and argued that they will help us get more external contributions, since that was an already recognized problem and easier to argue for. It seemed logical to me, coming from my experience. I.e. making it easier to understand the code would make it easier to contribute. There are other arguments I could have used, but they are harder to defend, and some of them especially so, since the team already knows the code well.

There were a variety of responses, but also one request for actual data on the effect of code documentation on number of contributors, which I came asking for here, after my Google searches failed. I.e. I'm asking for evidence, supporting or otherwise.

I agree that community composition is mostly a social issue. I'm intrigued by your description: "a community that makes changes by argument rather than consensus". Could you elaborate? I feel I could learn something here.

I would rather not specify the project to keep the discussion abstract and unbiased. Although for anyone really interested that information is a few Google searches away, I expect.

People might want to contribute fixes or small features, because the project is already quite widely used and is essential for bigger companies using Linux.

The question is asking for evidence to support an opinion. That opinion is held despite a lack of evidence. That's fine, in so far as it goes. In this case however, the opinion comes with a mandate that makes work for other people even though there is no evidence that the additional work will be of net benefit. For example, the community could devote 100 developer-hours per year to documentation that saves a total of 2 developer-hours per year.

In this case, a proposal was made, someone asked for evidence and the person making the proposal realized their was none. The culture of the community is such that the response was an effort by the proposer to win the argument that runs against the general consensus of the community. Even though the proposer acknowledges a lack of evidence to support the proposal and can reason that their own proposal was made on the basis of something other than evidence.

That's sort of what politics or community infighting etc. look like. The advantage arguing over opinions offers is that actually reaching out and engaging potential community members is harder than saying "We need more documentation". That's a common manifestation of XY Problems in social/community settings.

To step to a higher level, the language -- "argue", "defend", and "would have saved me time" -- occasionally work in unusual circumstances. But a lot of people don't enjoy arguing over things that don't really matter very much. Such people will simply walk away no matter how good the documentation is.

To put it another way, an unwillingness to name the project shows exactly how this is an XY Problem. The means are at odds with the ends. The fight club is probably not a good model for a software project.

Good luck.

Thank you. I have to admit, that it's again hard for me to pinpoint what exactly you're answering to and what's your argument. Either because I'm not that smart, I'm unwilling to accept some of what you say (for whatever psychological reason/bias), it is somewhat obscure, or all together. So, please forgive me, if I fail.

First of all, I'm not sure this is exactly an XY problem, because I started the discussion describing what exactly I was doing, what difficulties I faced, and how documentation can help solve them, in my opinion (yes, opinion). So there was no confusion what I want to actually achieve. I.e. faster and easier understanding of the code, which is the primary function of documentation. I.e. you read documentation, instead of reading code (sometimes many functions deep), thus saving time and effort. At least with sufficiently good documentation.

A counter argument was that documentation is not necessary, and the code alone is enough. Another was that tests are better than documentation, because they're verified to be correct. One person replied that when they started, they also tried to write documentation, but were discouraged by the project leader, and now they also support that approach. All of that is beside the point of the discussion, although provides context.

Yes, there is no evidence supporting the particular argument I was using. I was attempting to use logic and induction to change other people's opinion, so that they don't see documentation as a thing that "doesn't matter very much". It is hard to evaluate the effect of documentation and provide evidence without extensive data and research, similarly to how it is hard to evaluate why exactly the developer time was spent. I would be glad to see evidence, though.

OK, now I'll try to calm down a little, lower my defenses, and dig at the root of the problem.

The code is a mess, there is a metric shitload of it, and it is hard to understand. I wanted no more of that pain, and I wanted to have that fixed. I.e. to have the code easier to understand, no matter how. Perhaps this is exactly what I should have written. Instead I simply wrote that the code was complex (which is true enough) to try not to trigger other people's defenses, thinking that perhaps arguing for the documentation would be easier. I know that documentation helps, in many ways, but it would be just one way of fixing it. That way was also against the popular opinion, as it turned out. I may have also had a bias against people doing "the wrong thing" (TM), since I always document my own code.

So, perhaps, this situation and my approach is what you mean by the XY problem. I don't think that my proposed means are completely at odds with the ends, but I agree that they're unnecessarily limiting, rigid. I think that I would have been better off simply raising the issue itself and asking for solutions. Especially, since that particular piece of code is already considered problematic by many. Perhaps that's what I'll do.

I had issues with some people from that community before, and I do have my own communication difficulties, which makes it more complicated, and perhaps contributed to my choice of approach. Perhaps I'm a considerable part of that particular community problems too.

Please excuse me, if the above attempt at self-reflection is too personal for a stranger's HN comment. Thank you.

Thanks! Yes, I hear the same from them and I try to consider this approach :)

It is an additional effort, for sure. It is not without its benefits, though, and I'm trying to find out if it's worth it.

Why I originally brought this up with them is because I started working on a feature and found the code barely comprehensible. I spent a lot of time to try to keep everything in my head and failing repeatedly and felt like documentation would have helped me a lot. I.e. I was exactly in the position of a new external contributor and found the experience lacking.

Aside from the comments above, I would add "shopt -s shift_verbose" which enables "overshifting" detection.

E.g. when a function receives less arguments than necessary and you retrieve them like this:

    function f()
    {
        declare -r x="$1";  shift
        declare -r y="$1";  shift
        declare -r z="$1";  shift
    }

with less than three arguments passed and shift_verbose on you will get an error message the moment you shift and with "set -e" in addition, execution will be aborted.

See https://www.gnu.org/software/bash/manual/html_node/The-Shopt...

Also, "set -o noclobber" might be useful. If you try to redirect to an existing file with ">", it will fail. If you explicitly want to overwrite the file without triggering the error, use ">|".

See https://www.gnu.org/software/bash/manual/html_node/Redirecti...