53 lines
2.3 KiB
Markdown
53 lines
2.3 KiB
Markdown
## 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.
|
|
3. A directory corresponds to a title, and readme.md in this directory is its content. Other documents in this directory is its sub-sections.
|
|
4. 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
|