Accessor Documentation: A property of the "Property Definition" folder?

[Mr._Jim]

Hi all,

When creating accessors, I find that 99% of the time my read and write accessors have the exact same documentation.  I'm literally copying and pasting into the "VI Description" for each pair of accessor VIs.

For example:

Let's say I have a data member called timeout_ms.

Whether it's the read accessor or the write accessor, the documentation is, "VISA timeout in milliseconds for serial transactions."  Entering it twice, while routine, has become mildly annoying.

Why not make the accessor documentation a property of the "Property Definition Folder" that houses each pair of accessors?  That way, most of the time the developer would only have to enter documentation once.

How might this work?

1. The developer would open the context menu for the accessor's property definition folder.
2. From the context menu, the developer would select "description", "documentation", or some such item.
3. The developer would then enter a description of the data member in the resulting window.
4. After clicking OK, the dialog would then apply that documentation to the VI description for both accessors.

The dialog might look something like this:

I'm a real stickler for VI documentation, and as much of a hassle as it can be, I document all of my accessors.  Any time we can reduce the number of mundane steps to accomplish basic things, I'm very grateful.

Thanks as always,

Jim

[AristosQueue (NI)]

I agree with the general sentiment: "It should be easier to write documentation for property VIs."

I'm not thrilled about your proposed solution. So let me give you some back story and then see if you can propose a better way that would make all parties happy.

What you see is the compromise solution to an unwinnable argument. The argument:

"Documentation for read and write should be identical because you're talking about the property itself. (Therefore you shouldn't have to write it twice)."

vs.

"Documentation for read and write should never be identical because the write should include values that cause errors (or a note that none cause errors) and read should include conditions under which the value is unavailable (or a note that there is no such condition)." 

And then there was the splinter group: "No matter what, we don't want another place that users have to check for documentation. It needs to be on the VIs somehow because when a user *does* fill in the documentation for a VI that happens to be in a property folder, we don't want them wondering why the text doesn't show up in CH, especially for VIs that didn't start off in a property folder."

I suggested at one point that we should use the documentation from whichever VI you were using (read or write) and if that VI had an empty description then use the description from the other VI. This made neither group happy.

So it seems like something is needed that lets you use the UI to edit both VI documentation fields simultaneously for the "keep them identical" crowd and lets them be edited separately for the "make them different" crowd. I just don't know what kind of UI would make that clear -- when a person uses VI Properties, explaining that just this one page of properties (description, help tip, help link) is actually editing two VIs is trickly.

[Mr._Jim]

Ah, okay.  If I understand correctly, I think what I proposed may be a solution, and a compromise that accommodates both camps.

I wasn't originally going to get into the nitty gritty, but here it goes:

1. The solution I'm proposing still reads and/or modifies the "Documentation" field under "VI Properties" for one or both accessor VIs.
2. I am definitely not proposing a replacement documentation field, or a separate one that is associated with property definition folder.
3. The dialog I mocked up (above) just provides a convenient way to access the two "Documentation" fields of the two VIs, respectively, in one place.
4. If the user has already entered two separate VI descriptions and opens the dialog, the following would happen: The dialog would compare the two descriptions for the accessors.  If the two descriptions are identical, the "use identical descriptions" checkbox would appear checked.  If they aren't identical, the checkbox would be unchecked and the respective descriptions would appear on the respective tabs.  (Clear as mud? )
5. Regardless of how the user fills out the dialog (identical descriptions or not), the "Documentation" field is applied to both accessor VIs.
6. If there is only one accessor, then the other tab and the checkbox would be grayed out, with the appropriate tab already set to the foreground.

I really hope I haven't convoluted this beyond all recognition.

Please let me know if something isn't clear.  Of course, it's clear to me!  I hope that if I get your kudos vote then others may jump on the bandwagon.

Thanks again,

Jim

[AristosQueue (NI)]

It's a reasonable approach. I asked for the gritty details because some of this is about finding a UI interaction that customers would actually like.

Let me ask you this: What behavior would you expect when you opened the actual VI Properties dialog box for one of these VIs. Should we let you edit it (and maybe mislead people into thinking they're editing both), do the same as if you had gone to the property properties, or gray those fields out and tell people they have to use the property properties (even if they are setting them to different things)?

Similar question applies when we start talking about the programmatic case of writing the documentation through scriptiong.

[Mr._Jim]

Your point regarding potential confusion is certainly valid.

What I'd envisioned was letting users access the existing interface (VI Properties) as before, or optionally the property properties using the new dialog.  ...or they could use scripting and set the VI documentation, same as before.  Because the way the documentation is being stored still isn't changing, the scripting API would stay the same.  I'm really only suggesting a UI enhancement that is completely backward compatible.

[AristosQueue (NI)]

Ok. Thanks.

[Mr._Jim]

Thank you.  ...for taking the time to read and consider all of this, even though not many people will probably be interested in it.  I appreciate it.

[Gajic4x4]

When you right click on a single selected VI in the project explorer, one of the options is "Properties" from which you could navigate to the Documentation tab and put whatever you want.

How about if you could select multiple VIs and then see "Properties" when you right click? The properties menu could show the subset of settings that it makes sense to be simultaneously editable on multiple items (such as documentation). You could also do things like set the reentrancy settings or window appearance simultaneously.

An analogy would be selecting multiple files in windows, right clicking and opening properties lets you set attributes simultaneously for all selected files.

[Mr._Jim]

Gajic4x4, I'd encourage you to start a new post with your idea.

The reasons for this include, but are not limited to:

1. Your idea is similar to what I'd posted, but not exactly the same thing
2. People will be able to vote exclusively for your idea (they can't right now, because you're piggybacking off of mine!)
3. In general, when there are digressive comments on any given post, it obfuscates the original idea, and people become unsure of what they're voting for.

Good luck, and welcome to the Idea Exchange!

Mr. Jim

[Darren]

Any idea that has received less than 4 kudos within 4 years after posting will be automatically declined.