03 Documentation

• Comments should explain the „why“, not the „how“
• Using hashtags (see below) enables Bookmark Manager usage

• Case Structures

  • Display label and put a question describing the purpose of the case structure
  • Display subdiagram labels and answer the question for each case
  • Optional: Color the expected case(s) - the “sunshine scenario” - in light green (RGB = 225/255/225)
  • Optional: Color errors in light red (RGB = 255/225/225)
  • 

• Subdiagram Labels are to be displayed and filled with text

  • Exception: Error Structures
  • Tools → Options → Block Diagram → Tip Strips & Labeling → Subdiagram Labels visible by default

• Constant Labels are to be displayed and filled with text

  • Tools → Options → Environment → Show created constant labels

• „File → VI Properties“ or „<Ctrl>-I“

  • Select category „Documentation“
  • „VI Description“ contains the text that is displayed in the context help window

Quickstart VIs will have a comment placed on their block diagram as follows:

  This is a quickstart VI: A very simple example for using this package.
  
  This project ships with several examples which you can browse from 
  the Example Finder ("Help -> Find Examples…" menu item in the LabVIEW IDE).
  In the NI Example Finder, browsing the directory structure, navigate to "\HSE" 
  or "\Hampel Software Engineering" where you will find additional example VIs.

• Every project needs a readme.md

  • sits at the root of the repo
  • describes the basic structure
  • links to resources (like hie-libs documentation)
  • lists dependencies and requirements (also .vipc?)

Use PlantUML for server-side generation of diagrams from plain markdown text. Both Dokuwiki and Gitlab support PlantUML.

  ```plantuml
  @startuml
  Alice -> Bob: Authentication Request
  Bob --> Alice: Authentication Response
  Alice -> Bob: Another authentication Request
  Alice <-- Bob: another authentication Response
  @enduml
  ```

  <uml>
  @startuml
  Alice -> Bob: Authentication Request
  Bob --> Alice: Authentication Response
  Alice -> Bob: Another authentication Request
  Alice <-- Bob: another authentication Response
  @enduml
  </uml>

See Processes/Dokuwiki for a rendering example.

• If there is an external source of information, then mention it or link to it on the block diagram

  • eg when reimplementing an algorithm from a text-based programming language, add a screenshot of the code fragment
  • when working towards external specifications (eg implementing a protocol), link to the official documentation

• Generates dokuwiki pages from VIs
• see https://code.hampel-soft.com/hse-labs/documentation-generator/ repository