Introduction
This document lists some basic rules that must be followed when writing a document for the Denodo Knowledge Base.
Global Style Guidelines
Acronyms
There are some commonly used acronyms such as FTP and HTTP that do not need to be spelled out. All others should be spelled out in their first occurrence and followed by their acronym in parentheses when first mentioned in a document, e.g. Virtual DataPort (VDP). After first mention, the acronym can be used alone.
Alignment
Text should be justified rather than aligned to left or right margins.
Screenshots
When adding a screenshot try to include only the part of the window/screen that is relevant, making the image as small as possible to make sure it is easy to see. Check that any text included in the screen shot is easily readable.
Center-align the images and leave an empty line before and after the image in the document.
Labels and Code
Use Consolas or Courier New as font for labels and code:
- Labels for actions, buttons, check boxes, drop-downs, menus, parameters, etc.
- VQL sentences.
- Programming Language Code.
- Placeholders.
- Shell commands.
- Scripts.
- Paths
- Values provided as examples.
- Users and password.
- Configuration files.
Code
For short fragments of code (code, VQL, scripts, shell commands) of one or two lines they can be included inline in the document using the Consolas or Courier New fonts.
For longer fragments it is better to include them inside a 1x1 table to include readability
$ My command
SELECT *
FROM myview
WHERE myfield = myvalue
Placeholders
When referencing a path or a value that the reader of the document is supposed to change when following the instructions the placeholder will be enclosed by the < and > characters and we will use upper case. For the most common placeholders we should always use the same name:
- <DENODO_HOME>
- <SOLMAN_HOME>
- <HOSTNAME>
- <PORT>
Hyperlinks
When including a link to an external document use the normal hyperlink quick style (blue and underlined). The label for the link should be the name of the document or section that you are referencing, do not use labels like “here” or use the link as it is.
Menus
When referencing a menu use their exact label text, including capitalization.
For “context menus” use this term and use right-click as the action to access them.
Avoid Passive Voice
Try to avoid passive voice and use active voice whenever possible. Use “you” as the subject of the sentences when giving steps or instructions to follow.
Contractions
Do not use contractions.
Product Naming Conventions
Names of Denodo tools/webapps/solutions/components must be preceded by “Denodo” at least for the first occurrence of the tool in the document, except Agora.
Shortened forms are OK to use after a first mention of the component, for instance, Denodo VDP can be used but only after a first mention of Denodo Virtual DataPort.
The following list includes the names of the different Denodo products as they should be used in our Knowledge Base:
- Agora
- Denodo Platform
- Denodo Platform Control Center
- Denodo Express
- Denodo Professional
- Denodo Enterprise
- Denodo Enterprise Plus
- Denodo Scheduler
- Denodo Scheduler Administration Tool
- Denodo Virtual DataPort
- Denodo Virtual DataPort Administration Tool
- Denodo Web Design Studio
- Denodo Data Catalog
- Denodo Solution Manager
- Denodo Solution Manager Server
- Denodo Solution Manager Administration Tool
- Denodo License Manager Server
- Denodo Monitor
- Denodo Diagnostic & Monitoring Tool
- Denodo Dashboard
- Denodo Embedded MPP
- Apache Zeppelin for Denodo
- Denodo Dialect for SQLAlchemy
Elements Created in Denodo
When you need to include references to the elements created in Denodo (data sources, views, data services, interfaces, associations, etc.), please follow these naming conventions:
