Documentation Guidelines

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

• When writing user or developer documentation, the reader should not be addressed directly in the documentation.
• Example: Instead of writing “You find further information here…”, it is better to write “further information can be found …”.
• Only exception in this dokuwiki is First Steps in DOKA-NG, where personal speech is used for an initial instruction to a user of this application.

Write text only outside of auto-generated text blocks“:

• Any text written in dokuwiki between the tags /* id="TD_Start_ ...."*/ and /* id="TD_End_ ...."*/ had been auto-generated by GENWIK.
• This means that, when a manual text has to be added, it should always be written after the /* id="TD_End_ ...."*/ tag. If not, the manually added text would be overwritten with the GENWIK run.

No cross-references between “Application Documentation” and Developer Documentation”

• Cross referencing between books must be avoided. This means that, do not provide links to a page that falls under “Developer Documentation” from “Application Documentation”.
• Reason: Many external users do not necessarily have access to “Developer Documentation” and providing such links in between the document itself ends up in a corrupted links.

English

• “American English” (English: US) is used in this documentation.
• “American English” is the main language for documentation.
• Translations in this documentation are based on the “American English” version.

German

• For documentation in German: “German: Germany” is used.

Spanish

• For documentation in Spanish: “Spanish: Spain” is used.

Usage of “double quotation marks” and 'inverted commas' or 'single quotation marks'.

• Write between “quotation marks” or 'inverted commas' names and description which refers mainly to the application's graphical user interface (GUI).
  • field labels
  • checkboxes
  • combo boxes
  • panel names
  • icons
  • buttons
  • checkboxes
  • Transaction names, if not 'automaticall displayed' with links

Formatting of text:

• This application uses translation tools, but they problems with formatting symbols in “dokuwiki” sentences.
• Therefore, the following has to be recognized.
• Avoid the formatting options “italics”, “bold” and “underline”, despite they could technically been used in “dokuwiki”.
• Do not format text in italics by using “double slashes”.
• Do not format bold text by using “double asterisks”.
• Do not underline text by using “double underscore symbols”.

• Do not format text into “italic letters”
• Example: 'The field “Confirmation from 1st Adv. Bank” shows, whether the …'

Terminology quotation

• Always quote the terminologies and names like they displayed in the user interface of application (English and German UI). This applies to fields labels, panel names, combo box entries.
• When referring to a field name, panel name etc., it might be necessary to use capital letters in between a sentence.

• All images should be stored as .png files
• All file names including the file extension in the images folder must be in small letters/ lower case, e.g. image.png
• Images are stored in \dokuwiki\data\media\images (see detail information of the correct folders below)

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.

• Since the developer documentation is provided in English only, there is no subfolder to differentiate for the language.
• Images in these folders will be overwritten by GENWIK.
• Automatically added images of GENWIK are typically images of the transaction panels. These images are stored in the following folders:

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.

• When adding a manual screenshot to the user or MyModelbank documentation, it must be saved in the languages supported by the application, i.e. in English and German at the moment. If your screenshot contains processing data of the transaction, take the screen shot with the English user and directly afterwards with the German user. This will help to save time in recreating the contract data.

• Manual screenshots of the user documentation must be stored in the \app_man folder i.e., en\app_man for English and de\app_man for screenshots using the German User interface language.
• Manual screenshots of the MyModelbank documentation must be stored in the \dem_man folder.
• Manual screenshots of the developer documentation must be stored in the \dev_man folder.

• Images in these folders will not be overwritten by GENWIK.

• Screenshots must be stored with the same filename in the folder for English (\dokuwiki\data\media\images\en\app_man) and German images (\dokuwiki\data\media\images\de\app_man). This helps to ensure completeness of image files in all directories. The file name should briefly describe the image and it must be in English.

• The images with the flowcharts (e.g. Flowchart Business Sector Import L/C) or the partymodel (e.g. Party Model -Import L/C) are screenshots taken from slides that are prepared in powerpoint application. If changes to these images are required, the original source of the image file must be edited.
• The original powerpoint files of these images are stored in the folder \doku\charts of the application. Both English and German content is stored in the same powerpoint file. After a change is made to the original file, the updated version must also pass the review and QA step and has to be checked in like any other source change.
• Guidelines to create the party model, flowcharts have been created and stored in the folder \doku\charts (Guidelines.pptx) of the application. Always adhere to these guidelines when creating such diagrams.
• Sample flowchart (btoxx_sample.pptx) and partymodel (broxx_sample.pptx) has also been placed under the same location which can be used as a base to create any new diagrams.

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:

• Use the same terminology, spellings across the document as in Dokuwiki and in the application.
• Use bullet points instead of numbers when required.
• Use table of figures and label each figure used in the document.
• While creating PDF's from the word document, create bookmark using the chapter headings, this creates a proper navigation.
• Document name must be inline with the older versions/documents.

Business wordings and translations are available in Business Words (English - German).