This thread has been about how much more backstory the AF documentation needs to have. I think documentation of that sort is best left on the forums and NOT in the LabVIEW product or hands-on session. I have tried with the AF shipping documentation to follow a route very similar to the route taken with the OO programming, only this time I did not have the benefit of April Griffin nee Brinkmeyer, technical writer extrordinare. She created literally award winning documentation for LVOOP in no small part by paring down a lot of the OO philosophy that was in my original draft, making it accessible to users on their own and signposting that, if they were interested, there was more to this OO world that they might find online or in books. I tried to follow the same pattern with the AF documentation, but some part of me worries that I didn't pare it down enough.
The AF was designed to be powerful enough for the high level users on this list. I wanted it for my own software development. Indeed, I felt LabVIEW needed something to bring order to the chaos at the high level architecture levels. So it is a robust tool, capable of expressing great subtlety, and it makes its pro/con tradeoffs, the same as any other tool. It is a tool designed for the tip of the user pyramid.
But what really spurred it's development were e-mails to me from users at the middle of the user pyramid. I try to discourage users from e-mailing me directly because I don't have time to handle every request and often the online community can give as good or better an answer than I can alone. But some do e-mail me anyway when they get desperate, on the off chance they catch me on a good day. The following is the boiled down text of multiple e-mails that I got between 2008 and 2010 from users:
"Hi, I'm a LabVIEW user. I've been given an assignment to build this multi-part industrial control system. It has several parts working in parallel that need to communicate with each other. I've got the whole thing working, but it won't shut down. I can't make it stop except by quitting LabVIEW. Can you look at my code and see what I'm doing wrong? I've been programming LabVIEW for a couple years now, maybe thinking about trying for my CLD, and I'm the only LV user in my company, so I don't have anyone else to ask."
This is the person I had in mind when I wrote the main documentation for AF.
I've now worked with a lot of people to explain what was wrong with their ad hoc messaging system. I've tutored a lot of people in the use of the AF. I've spent time doing both one-on-one sessions and large lectures. What I realized over time is that these folks were being asked to do projects that exceeded their own experience with software development, and they were flailing against something like "blank diagram syndrome", only this was "blank project syndrome". They had no idea how to build the architecture they needed for their project.
If I am going to help those users, I am *not* going to teach them 15 different ways to accomplish the same task and giving them guidelines for picking the right one. I am going to say, "This is *a* right answer. Do this to accomplish your task." Are there cons that they will encounter with that path? Sure. But for the most part they will never know they encountered those cons.
For example: "You need to decouple static binding between modules in order to get editor performance." No, not really. The Feedback Evaporative Cooler shipping example, including the VIs from vi.lib, is about 260 files (libraries and VIs). Performance of the editor there is fine. The only non-static binding there is the one that needs to be there for the project requirements -- the ability to swap UIs on the fly while leaving the cooler running. And even with that, there's a hefty amount of code reuse possible from that project. Will you have a few things slow down at 500 files? Sure. But is it significant? Not when compared to not getting the job done at all.
In other words, the AF was designed to solve a tip-of-the-pyramid problem but documented for someone with middle-of-pyramid experience. The users targeted by my documentation are the majority of LabVIEW users whose entire VI hierarchies load into memory when they open their top-level VI who find themselves having to make the leap from a simple producer-consumer to a multi-part system, on their own. I'm trying to offer them the AF as a way to handle that sudden jump in complexity in a way that gets them working without making the documentation a six week course in architecture.
The advanced conceptual backstory of the AF is exactly where it needs to be -- in the forums, in web casts, and in the heads of the other CLAs who lurk about.
I hope Daklu and Staab keep this in mind when they create their NIWeek presentation: Their presentation will NOT be an introductory presentation for new AF users but will instead be an advanced presentation for architects. Presenting the other options and the philosophy of design is, in my experience, at minimum unhelpful and often actually harmful to a new user of the AF. The information is good, and I encourage them to present their findings, but not to pitch it as if they're making AF adoption easier for a user. I would make a similar recommendation to any of the rest of you who teach the AF in a lecture setting or in documentation fired into cyberspace. Only a teacher who is going to be around the student through their whole learning/adoption process has the luxury of presenting theory mixed with practice. Everyone else, stick to the basics, and let the students find their way to the forums when they reach the point where they need more input.
