yakindu/plugins/org.yakindu.sct.doc.user/hints_for_writers.textile

h1. Hints for writers

h2. Anchors

* An anchor in a top-level section has a section-specific unique prefix:
| *Prefix* | *Top-level chapter* |
| advsim | Advanced simulation and debugging |
| cdom | C domain |
| edit | Editing statecharts |
| cgen | Code generation |
| glsr | Glossary |
| hdls | Headless code generation
| ovvw | Overview |
| sctu | SCTUnit |
| simu | Simulating statecharts |
* Underscore
* Figures
* All lower-case letters
* Prefix + headline




h2. Conventions

* *Names* are formatted in _italic_. This pertains to all kinds of names, including GUI elements, files, and folders. Examples:
** Click on the _Format drive_ button. In the confirmation dialog, click on _OK_.
** Select _Window → Preferences_ from the main menu. The _preferences_ dialog opens.
** Copy the _superstuff.jar_ file to the _lib_ folder.
** Word files have a filename extension of _.doc_, _.docx_, or _.docm_.
* Keystrokes are formatted with square brackets and in @monospace@. Examples:
** To reboot, hit the @[Ctrl]+[Alt]+[Del]@ key combination.
** Um einen Neustart durchzuführen, drücken Sie die Tastenkombination @[Strg]+[Alt]+[Entf]@.

bq. *Please note:* Exceptions are a confirmation of the rule.




h2. Orthography

* A sentence has to be terminated with a full stop (.).




h2. Typography

* To write a *dash*, please use the endash symbol (–). Don't use the minus symbol (-) as a replacement.
* To mark an *omission* in a text, please use the ellipsis symbol (…). Don't use three dots (...) as a replacement.




h2. English

h3. German English

Please beware not to get trapped by typical "German" pitfalls!

* Compound nouns: Don't hyphenate the compounds, but rather separate them by a space character. Example:
** *Wrong:* -While a Java-file contains Java-methods, a C-file contains C-functions.-
** *Correct:* While a Java file contains Java methods, a C file contains C functions.
* Nouns: Start nouns with lower-case letters. Example:
** *Wrong:* -Let's consider this Artifact Type.-
** *Correct:* Let's consider this artifact type.
* Names: Spell a name with a capital first letter. Examples:
** Java
** Microsoft Word
** Enterprise Architect
** YAKINDU Traceability



h3. Typical spelling mistakes

| *Right:*     | *Wrong:*     |
| double-click | double click |
| read-only    | read only    |




h2. Earmarking transitional statements

Certain statements in a documentation are transitional by their nature and should be checked from time to time. For example, consider the following sentence:

bq. As of this writing (winter 2016/2017), component C is the only one to support system S.

This sentence makes two transitional statements:
* The time of this writing is winter 2016/2017.
* Only component C supports system S.

In order to easily identify and check such transitional statements, CHECK comments are used. For example, close to the above paragraph the following CHECK comments should be added, making the complete source look like this:

bc.. 

 ###. CHECK: The time of writing is still winter 2016/2017.
 ###. CHECK: System S is still only supported by component C.

 As of this writing (winter 2016/2017), component C is the only one to support system S.

p. Searching the documentation for all occurences of @###. CHECK:@ is very easy. It is advisable to include the transitional statement on the same line as @###. CHECK:@, because this way you can simply "grep" all textile source files for the string @###. CHECK:@ and immediately see all the transitional claims that are made. In the most simple case all you need to do is browse them, verify that nothing has changed, and you are done. Only if some statement is no longer true you actually have to go to the corresponding documentation file and update it. Don't forget to also update the CHECK comment accordingly!