Welcome to the Exasol Knowledge Base (KB)! This repository contains files and information needed to create a KB article.
Exasol KB articles must be created using Markdown (.md) format. If you are new to Markdown, see Markdown Guide's Getting Started section. There are also many programs that will convert, say, Microsoft Word (.docx) files to Markdown files.
Your final article will be converted to HTML and rendered on the Exasol Knowledge Base website. Please use only basic Markdown syntax.
Note: Using other flavors of Markdown may not work as expected when rendered on Exasol's website. Even some basic syntax does not work as expected. For example, do not use Blockquotes ( > ).
You can choose one of the following templates:
- Question and Answer: Pose a quick question with a specific answer.
- Solution to a Problem: Provide workarounds for bugs or new shortcuts that you would like to share with others.
- Tutorial: A quick tutorial for a specific task.
The knowledge base provides five categories:
- Connect With Exasol
- Data Science
- Database Features
- Environment Management
- Support and Services
- Access the GitHub repository at exasol\Public-Knowledgebase.
- In GitHub, click Fork or create a new branch.
- Select the appropriate template in the Templates folder and copy the content.
- Using your tool's commands, create a new file in the matching folder and copy the template's content into that file.
- Save the file in the appropriate category folder.
- Write the article using styles listed in the Exasol Styles section of this readme and instructions in the template.
- Each category folder contains a subfolder called images. If you have images, place them in your chosen category's images folder. Make sure the size of each image does not exceed 1 MB.
- We recommend you use a Markdown linter locally, to make sure required formatting rules are applied. The pull request you will create will be subject to a linter check online.
- Once you are happy with the article, use your tool to commit and push the changes.
- In GitHub, click Pull request, New pull request, and then click Create pull request.
Please keep in mind the following limitations when creating or modifying KB articles:
- Images must not be larger than 1 MB.
- Do not include the
<or>symbols in your Markdown in plaintext parts of the article, they might get interpreted as HTML tags. If you need to use those symbols, use<or>instead to represent those characters. - Symbols
<or>should, however, be used inside code blocks (triple ticks) and code inlines (single ticks). - Use
<br />instead of<br> - Article should contain only one level 1 header (starting from a single hash sign #). Any content starting from the second single hash sign will not be rendered in Salesforce Knowledgebase.
- Tables need to be separated from the surrounding text by at least one blank line from above and below.
- As images should go to a special subfolder called "images", they should be further used via a path relative to a current folder, like (uppercase fragments are to be replaced accordingly)
Exasol's official style guide is the Google Style Guide. Reference all questions there first. If the Google Style Guide does not answer your question, as the Google Style Guide recommends, go to the Microsoft Writing Style Guide.
Some Exasol styles do differ from Google and Microsoft, and Exasol is in the process of changing styles to more align with Google. Please scan the following style guide for information on Exasol specific styles.
- Text formatting-summary: Provides Google formatting notes for markdown documents.
- Google Style Guide
- Google Word List
- Microsoft Writing Style Guide: Use when the Google Style Guide doesn't answer your question.
- Markdown Linter CLI 2: An implementation of a Markdown syntax checker, which is also available as plugin for Visual Studio Code