doris/docs

Philosophy

write once, use everywhere

Documentations will be written once, and will be converted to other format according to different application scenarios.

Implementation

         +---------------+
         | Documentation |
         +-------+-------+
                 |
         +-------+-------+
         |  Doc Builder  |
         +-------+-------+
                 |
    +--------------------------------+
    |            |                   |
+---+---+    +---+----+        +-----+----+
|  PDF  |    |  HTML  |  ....  | Help Doc |
+-------+    +--------+        +----------+

Documentation：Text contents which is written by human. And this is the only place for documentation. Doc Builder: Tools that convert documentations to other format, such as PDF, HTML. There could be many tools, and we can use different tools to convert documentation to different formats.

Organization

docs/documentation: Root directory for documentation. And for different languages, there is a root directory for it. For example, docs/documentation/cn is the Chinese documentation's root directory. docs/scripts: Place of Doc Builder.  docs/resources: Resources that are referenced in documentation, such as pictures.

Constraints

1. All documents are written in Markdown format, and file name is end with ".md".
2. All documents are started with level 1 title # Title, and should have only one level 1 title.
3. Names of file and directory are in lowercase letters, and use dashes as separator.
4. Documentation can be constructed as a directory or a single Markdown file, these two formats equal with each other in logical. Relationship is represented by parent-child directory in directory format, and by title level in file format. It is recommended to use directory format to manage a large documentation, because it is easy to maintain.
5. A directory corresponds to a title, and readme.md in this directory is its content. Other documents in this directory is its sub-sections.
6. For manual like section, such as function description, there should be Description, Syntax, Examples section in documents.

level directories

1. doris-concepts
2. installing
3. getting-started
4. administrator-guide
5. sql-references
6. best-practices
7. internals