Writing documentation should adhere to the following guidelines to ensure that the documentation is consistent.
Continue to use the standard wording that is already used in the documentation for common features and functionalities. Be sure to familiarize yourself with what is considered standard wording before writing documentation.
Helpful in this respect is First Steps in DOKA-NG which covers common DOKA-NG terminology, Business Words (English - German) for trade finance vocabulary and the below section Commonly used application wording and translations.
Personal addressing and instructions
Write text only outside of auto-generated text blocks“:
No cross-references between “Application Documentation” and Developer Documentation”
English
German
Spanish
Usage of “double quotation marks” and 'inverted commas' or 'single quotation marks'.
Formatting of text:
Terminology quotation
Images in Dokuwiki are either added automatically by transaction Generating Documentation (Wiki format) (GENWIK) or Manually Created Hardcopies in the Documentation by the user. To create images for MyModelbank contracts, follow the steps mentioned in Update MyModelbank Documentation.
Path | for … |
---|---|
\dokuwiki\data\media\images\<language>\app | For user documentation |
\dokuwiki\data\media\images\<language>\dem | For MyModelbank documentation |
\dokuwiki\data\media\images\dev | For developer documentation: |
Taking a screenshot of a certain business example with data filled in the processing screens is a great way to explain how a certain functionality works.
Many screenshots call for visual highlighting of relevant GUI elements, such as fields, buttons, checkboxes, etc. In order to achieve the highest degree of consistency in this area, users should create highlighting frames with a tool that should be readily available to everyone, viz, MS Paint or IfanView. As a general policy, users shall use rectangular shapes (frames) to highlight content. Retain a line width to five px, if required the width can be decreased but not increased. The color to use is Indigo (RGB - 63,0,255 / HEX -3f00ff).
The illustration below demonstrates the rationale of this policy.
In many cases, it will not be suitable to reproduce an image at original size. At the same time, Dokuwiki has an innate tendency to lose resolution when scaling down images (“blurring effect”). Until such time as this bug is officially fixed, the workaround involves embedding html code, as suggested by the following example:
<html><div style="width:550px"></html> {{images:en:app_man:some_image.png}} <html></div></html>
In technical terms, this semantics delegates the resizing process from the Dokuwiki engine to the browser used, which eliminates the unwelcome effect noted.
Documents such as the Release highlight document are created in MS Word and is published to the users in PDF. Along with the above mentioned points, below must also be taken into consideration:
Business wordings and translations are available in Business Words (English - German).
English | German | Comment |
---|---|---|
Abbreviations for Versus (vs.), Et cetera (etc.) | Use 'etc.' for Et cetera and 'vs.' for versus. Do not use abbreviations such as w.r.t for with respect to and any such not so commonly used one's. |
|
Acknowledgment | Acknowledgment | American Spelling |
allNETT | allNETT | |
Back-to-Back-L/C | Back-to-Back-Akkreditiv | Back-to-Back-letter of credit is also possible |
Bolero | Bolero | A customer-to-Bank/Bank-to-customer communication network. To be spelled preferably “BOLERO”, but “Bolero” is acceptable. For Bolero messages use: BOL423 |
button | Button, der | The same word is used in English and German. A button is always clicked, never pressed (in German “geklickt” anstatt “gedrückt”) |
checkbox | Checkbox, die | Use Checkbox in both languages. Do not use 'tickbox' or “Kontrollkästchen” in German. A checkbox is checked / unchecked /enabled / disabled. In German: “Eine Checkbox wird markiert/ die Markierung einer Checkbox wird entfernt, NICHT gesetzt oder angetickt, eine Checkbox ist aktiviert / deaktiviert”. |
codetable | Codetable | The same word is used in English and German. |
combobox | Combobox, die | The same word is used in English and German. |
Counter-Undertaking | Rückhaftung/Rückgarante bzw. Rückverpflichtung | e.g. ISCO = Indirektes Aval/Verpflichtung mit Rückhaftung/Rückgarantie |
Counter-Counter Undertaking | Rückverpflichtung mit Gegenverpflichtung | e.g.ICCO = Rückverpflichtung mit Gegenverpflichtung |
Corporate | Firmenkunde | |
currency (Cur.) | Währung (Währ.) | |
Display file | Display-Datei | |
For example, e.g., | z.b. | When starting a sentence with for example, do not start with the abbreviation. When abbreviation is used, it must be 'e.g.,' and not ex. |
DOKA-NG | DOKA-NG | do not use 'DNG' or 'dng' while mentioning about the product in the documents. |
entity | Entity, die | |
expiry date | Verfallsdatum | do not use “Verfalldatum” |
Export L/C | Export-Akkreditiv | In English, L/C is in caps, in German the correct spelling is with hyphen. |
helptext | Hilfetext, der | In EN + DE: to be used as “one word”. Not “help text”, not “Hilfe-Text” etc. |
Icon | Icon, das | Example in German: “das Icon <hier Bild einlinken> wird verwendet…” , so dass der Benutzer das Bild sehen kann. Size: 20 |
ID | ID | |
infotext | Infotext, der | In EN + DE: To be used as “one word”. Also “structured infotext” and “strukturierter Infotext”, but not “structured information”. |
INR | Unique internal ID | |
Liability | Engagement | |
limit; two limits | Limit, das; Plural: die Limits oder die Limite | |
multi-entity | Multi-Entity | |
Notify message | Notify-Nachricht | |
panel, panels | Panel, Panels | In German, do not write “Paneele”, when used with another noun, add a hyphen, e.g. “Auswahl-Panel” |
Party, pl. parties | Beteiligter, pl. Beteiligte | |
quotation mark ' | Anführungszeichen “ | Differs in German and English |
selection, to select | Auswahl, auswählen | |
status, two statuses | Status, der; Plural: die Status | DE: Die Mehrzahl von Status in DE wird ebenfalls “Status” geschrieben. Gesprochen liegt die Betonung auf der letzten Silbe, also “Statūs”. EN: In German spelling of “status” is indentical for singular and plural. Spoken the last syllable is ponounced = “Statūs”. |
stoplevel | Stoplevel, der | Do not use 'stopcode' |
stoptext | Stoptext, der | |
SWIFT, e.g SWIFT MT760 or SWIFT Score 762<760,761> | SWIFT, z.B. SWIFT MT760 oder SWIFT Score 762<760,761> | Do not use “S.W.I.F.T.”, but preferably “SWIFT”. Swift itself allows the spellings “Swift” and “SWIFT”. For SWIFT messages, use MT760 without space in between For Score messages use 762<760,761> For Bolero messages use BOL423 |
That is, i.e., | Das heißt, d.h. | When starting a sentence with that is, do not start with the abbreviation. When abbreviation is used, it must be 'i.e.,'. |
the bank using the application | die Applikation verwendende Bank | The term 'DOKA Bank' or 'DOKA-NG Bank' should not be used in the documentation unless necessary. |
user | Benutzer | Do not use “Anwender” in German |
you | man | The English word 'you', respectively the German word “man” should not be used in the documentation if possible. Instead of writing 'Then you have to click the button [xy]…”, it is better to write 'The button [xy] has to be clicked…'. In German, instead of writing “Danach klickt man auf den Button [xy]…”, it should read “Der Button [xy] wird danach angeklickt…”. |
ZIP file, ZIP archive | ZIP-Datei, ZIP-Archiv |