VI Documentation as an editable header on Front Panel

[ozimmer]

A major caveat about SubVIs documentation is failure to update description when code is modified. Also it is not obvious when opening a VI wether a documentation even exist for this VI (even though it is quite easy to figure out hovering the icon with Help Window on). At last, editing documentation in LabVIEW requires several clicks and menu browsing.

To help better maintaining VI documentation, I always write VI description as a text header on the VI front panel (top part) and replicate it into the official (burried) property field. Although redundancy generaly complicates proper maintenance, in this case it helps in many ways !

I therefore suggest VI documentation be integrated to the front panel as a header, when it exist. User may need to hide it for editing large GUI panels, but documentation header should always appear for SubVIs. It sounds logical to make it editable (to ease documentation maintenance again).

[Wart]

I'd like to see double clicking on the VI wiring terminal launch the description box of the VI properties.  The icon could still launch the icon editor.

But I agree that it's a little tough to keep documentation up to date... where it exists.

[SteveChandler]

Wouldn't this be better on the block diagram? There are many ideas for improving documentation on the block diagram.

As for the front panel I would rather see a new button on the toolbar. What about something like this?

[Darren]

I like this idea a lot, and I'd like to see the header on the diagram as well.  I think it would be a more robust manner to have self-documenting code than the traditional "big label" on the panel and/or diagram.

[ozimmer]

Re : FP or BD location ?

Displaying VI doc as a VI header on existing LabVIEW versions implies using a free text label with fixed size. I want this doc header be visible and readable at once without search and scrolls.

That's why FP has been a much better location for a "free text" header until now :

- FP tends to be smaller in size (scrolling generally not needeed)

- it reaches final/stable size earlier in the development process

- it is much less prone to expand upward or sideward during the VI's development

Now if LabVIEW would take off my header from FP or BD background and integrate it to the autosizing window part, I agree that locating it on BD window may be a clever alternative.

There are still reasons to consider locating it on FP though :

- VI documentation text is not an "inline" comment. It may clarify an internal algorithm, but mainly aims at providing a short factual description of what the VI does. It is close from a specification summary. It is not incoherent to disconect it from the diagram and locate it on FP, which puts forward synthetic, specifications-oriented and user-oriented items such as IO terminals.

- FP tend to be narrower (?) than BD windows. Text lines are harder to read when extending on a too wide area. They fit better in a narrower column.

[ozimmer]

Re : integrated header or shortcut button ?

Steve,

Possibility to display applicable documentation text along with other user-oriented FP contents clearly is an important feature to me, so I still favor the header approach over a shortcut button.
To allow hiding header (if needed ?!) I would favor a clickable down side separator.

[ozimmer]

Other implementation details or complementary feature would need to be discussed :

- Should header downward-autosize to content ?

- Should header downward extension be limited to a certain range (like 30% of the window area or so, or fixed height in pixels, in case description is much longer than the usual) and a scrollbar appear if it extends beyond this limit ?

- Should window autosize when header autosizes (I believe YES), or window content be pushed/pulled outside/inside visible window area ?

- Should it be visible by default (I believe YES) ?

- Should user be allowed configuring default visibility (or even BD/FP location) ?

- Should header offer a movable/clickable lowside separator, to allow user hide/show it or fix its heigth ?

[SteveChandler]

Ok you sold me. As long as it is not visible in run mode - kudos!

[SteenSchmidt]

I don't like wasting space on either the BD or FP for VI documentation permanently displayed. I like the idea that it should be easier to get to it though - double click on the con pane would be a good way to launch the VI Properties dialog with VI Documentation pre-selected. I don't think the double click action should be different from the BD and the FP, that would be confusing.

The VI documentation is edited rarely. I don't have a problem remembering to edit it, and when I've read it I usually have no problem remembering what the function does - or else I just have the context help window open (I usually just tap it open shortly to read help for the function/control I want, and then close it again). The FP interface should be well documented (control descriptions, captions), but the VI Description itself shouldn't be necessary to read constantly. My VI Descriptions tend to be quite long, since users don't have an option for detailed help (short of a link to a document, which is archaic), so my VI Descriptions would either not fit in such a space anyway (a scrollbar would defeat the argument of enhanced documentation, the description is still hidden until you scroll), or it would take up a huge amount of extra room on my screen (I often have many VIs open at a time).

/Steen

[GuessWho]

Could they possibly make the VI Doc window a floater, like context help?  Right now (LV10, anyway), my major beef with the documentation is that the window is modal, and you can't do anything else with the window open.  It's been that way for a long, long time.  The window should show me the doc for whatever vi is in focus, and be editable to boot.  Whatever I've got in that window when I close the VI should be saved as the VI doc.

2 cents, no more.

Blair

[johnsold]

I like the idea of more convenient access to the VI documentation.  Of the suggestions mentioned so far, I think I prefer Steve Chandler's toolbar button.  It should be available on both FP and BD and would bring up the VI Doc dialog with a single click.  Like SteenSchmidt I do not see the need to keep the documentation on the FP or BD screen all the time.  Blair Smith's request to make the dialog non-modal is worthwhile also.  Many times it is helpful to check something on the diagram or FP while entering the documentation (Exactly what did I call that Indcator?) and having it non-modal is much more convenient than opening and closing the VI Properties dialog repeatedly.

Lynn