On 5/3/22 8:40 AM, Rich NE1EE wrote:
On 2022-05-03 06:45:-0700, you wrote:
This kind of gets to a point - there *are* people who know the answers on this list, but in general, they also have other things to do, so their time is limited. It's great that you're taking on the challenge of writing a book to explain it, but as you know, it's time consuming.
To be honest, a threaded list isn't the best way to explain this kind of thing. The person who wrote the software generally has a good understanding of the theory, but doesn't necessarily have the time to answer it in a 20 questions form, and, it's also possible to be knowledgeable for writing the code, but not such a great explainer.
This gets to the heart of the matter.
there *are* people who know the answers on this list, but in general, they also have other things to do
Good for them. So do I.
It's great that you're taking on the challenge of writing a book to explain it, but as you know, it's time consuming.
All I set out to do is write a user manual for the nVNAs (-H and -H4, though it generally applies to other nVNAs). I figure that if I write down each feature as I learn it, then that will benefit hundreds? thousands? of those to come. Oh, wait, there are already people who know all this, and could have taken 30 minutes to think about the device and jot down some useful things that they know.
Indeed, but sometimes, (and this is particularly so on a forum like this), one doesn't know the desired level of the answer, audience it's intended for.? As an example, we've had a lot of discussions about calibration standards, and simple questions like "should I calibrate with or without the 6" jumper".? Some folks have a background in RF metrology, and want to make sure that we understand that a simple time offset may not be a good model. Others might be looking at an antenna between 5-10 MHz, for which it makes almost no difference.? Others, though, might be measuring phasing jumpers, so that extra 6-12" makes a difference.
This aspect of "finding the right level" is tricky, especially in a forum which is sort of asynchronous.? A person might pose a question and get 2 or 3 answers, all partially answering it, with different levels of rigor or formality. And then, 3 or 4 more others might respond with different aspects.? If we were all standing in a room doing this in real time, you'd pick up on some of the body language to manage the conversation. Likewise in a one-on-one phone call or remote presence - there would be cues to guide the questions, and followups.
I have long history with software engineering. That means writing requirements, a design, then software and software testing. We don't seem to have much of this.
This is definitely true, and it is characteristic of software that is produced to "scratch an itch", as opposed to "develop a product", particularly when it's done by one person. That's sort of a feature, not a bug. The author writes the software to meet some self derived requirements, which evolve based on time available, inclination, etc.? And if they understand it, that is sufficient for them.? In a lot of cases (e.g. NanoVNA and similar products) someone might push their software out for people to use, on a Use As Is basis, and if bugs are reported or features requested, then they may or may not do it, depending on their other desires.
This isn't unusual in volunteer activities - It's easy to find hams for a one time antenna raising party, less easy to find someone willing to drive up a twisty road, through locked gates, to clean the filters and check the battery water every 3 months.
I created the menu map in yEd because it is readily accessible, and anyone can update it from here out. So we have a Russian hacker who creates this stuff. I'm impressed with the talent. I don't speak Russian as well as he speaks English, and that is not very well. What I set out to do is write down what I think will help others new to the technology know what will happen when they press a button. That's why I posted that excerpt, to show what my intent was. I say was, because it didn't take long to exhaust resources. So, since I don't intend to spend hundreds of hours learning all this stuff, and there is not much feedback besides "look it up on the web", I figure /this/ part of the project is stalled.
And that's fine - you've made a contribution, others will extend or revise it, or you'll do it, or it will be like it is.? That's the way it is. The documentation on console commands is about 2 1/2 years old now (at least the version I have), as the result of Larry's significant effort. Unfortunately, it's a pdf, which is universally readable, but also makes it hard for someone to update.
So we fall back on the classic open source technique "read the code" and "rely on background information" - I use Scikit-RF at work, so does some of the NanoVNA software, so even without much in the way of comments, I can figure out what's going on.
I've created lots of requirement docs in the past. Lots of design docs in the past. Lots of programming and software testing. So it's not that I don't get it...I do.
it's also possible to be knowledgeable for writing the code, but not such a great explainer.
This is a good point. But for me, it's a show-stopper. Because when I ask a question, and there is no answer, there is nothing to write down. I assume that no one actually understands what the answer is.
Or, perhaps you can reframe your question, or maybe synthesize all the responses you got, and repose the question in that context.? It's a conversation, after all. This is, for good or ill, a largely text medium, which doesn't help when trying to describe how things are hooked up, especially when there are significant differences in terminology (not including bikeshed stuff like "is return loss negative?").? A lot depends on the background of the specific person. Someone who comes from a precision metrology background might use different terms than someone from a circuit design, or user background.? Little stuff like "uncertainty", "accuracy", "precision.
I've put the user manual aside. Maybe all that I want to know is there in Russian, but that does me no good. I certainly don't fault a Russian for writing in Russian. I actually started learning Russian years ago, because I thought of them as major players in the science field. But then most of the people I worked with spoke pretty good English...not great, but we could have a conversation, and I could connect the dots. So I stopped learning Russian. Rats. Well, too late to start now...
BTW, this discussion is not limited to this device. I spent 10 years working with PhDs who had the same lazy attitude. Too busy getting ahead of the next PhD to write down what they were doing. Before I left that group, they had hired //another// PhD to work in the lab ///// to reconstruct what had happened 10 years earlier /// because they were too lazy to write it down, and then had the misfortune to need it.
Well, perhaps it's not lazy (which is sort of perjorative) - perhaps it's that their requirements and incentives were not aligned with the others.? As a PhD candidate your *job* is to "get that dissertation completed".? It is generally not evaluated on the quality of the software and documentation you leave behind. That's sort of gravy. This is a typical complaint about new PhDs entering the industrial workforce. As a Phd Candidate, you're expected to do your own work. As an employee on a team, you're expected to share the work. As a PhD candidate, you're expected to be rigorous in derivations and references. As an employee in a team in a frenzy to get the "minimum viable product" out the door, you probably don't care as much about making sure the docs cite the seminal paper in the field.
