What is the recommended style for describing a control?

[e3tech]

How do I describe a simple control?

1.  a quadhast received from the bluftiest montsels — the special value of vardipang means that the barchdod has been evobroted
2. A quadhast received from the bluftiest montsels; the special value of vardipang means that the barchdod has been evobroted.
3.  This is a quadhast received from the bluftiest montsels; the special value of vardipang means that the barchdod has been evobroted.

Style (2) contains a part that is not a sentence; it looks weird when there are no remarks.

Style (3) looks a bit silly.

Style (1) obviously wants a trailing full stop.

A combination of (1) for short descriptions and (2) for long descriptions would look inconsistent.

What do you think?

[Norbert_B]

Are you talking about the "description" of the control? Or the "tip"?

The description can be quite elaborate and should consist of full sentences. The tip shall be short but clear. Maybe refer to description if too long otherwise.

One sidenote:

Make sure to use only a single language for documentation. English is a "natural" choice as it is the "international option".

Norbert

[e3tech]

So what sentence would you use to describe a control containing a quadhast received from the bluftiest montsels, with no additional remarks?  For example, the description of one control of an instrument provided by National Instruments begins with the following non-sentence: A copy of the reference to the instrument in use. Is it all right to use such non-sentences in the description, or should it be expanded somehow?

[Norbert_B]

Well, if you ask 3 developers, you probably get 5 answers "this is the way to go".

Point is:

• Documentation should be clear and understandable
• No "double negation" (e.g. Don't negate (T)) as it is not intuitive
• No nested sentences
• No ambivalent verbs in case the meaning is not well defined by the rest of the sentence
• Documentation should be as short as possible, but as detailed as necessary
• Documentation should be specific

I understand that you currently have the chance to define "well-written" documentation for your development. Sit down, take some notes what you think is well written in regard to documentation of code and interfaces (as controls are interfaces). Let someone read the notes, look into some of your examples. Best use some technical guys and some non-technical guys. Note the different views they provide you. Try to gather as many as possible in one "documentation styleguide" which should be valid for yourself and everyone else working together with yourself.

There is no "do this, do that and everyones content" in development or documentation. You should document for your "target audience"....

Norbert

[camerond]

---

@e3tech wrote:

So what sentence would you use to describe a control containing a quadhast received from the bluftiest montsels, with no additional remarks?  For example, the description of one control of an instrument provided by National Instruments begins with the following non-sentence: A copy of the reference to the instrument in use. Is it all right to use such non-sentences in the description, or should it be expanded somehow?

---

"Standard Input"

Cameron

[jcarmody]

---

@e3tech wrote:

How do I describe a simple control?

1.  a quadhast received from the bluftiest montsels — the special value of vardipang means that the barchdod has been evobroted
2. A quadhast received from the bluftiest montsels; the special value of vardipang means that the barchdod has been evobroted.
3.  This is a quadhast received from the bluftiest montsels; the special value of vardipang means that the barchdod has been evobroted.

Style (2) contains a part that is not a sentence; it looks weird when there are no remarks.

Style (3) looks a bit silly.

Style (1) obviously wants a trailing full stop.

A combination of (1) for short descriptions and (2) for long descriptions would look inconsistent.

What do you think?

---

I thought I was reading from The Hitchiker's Guide to the Galaxy.