0a4a5b36cc
* Additional .gitignore entries * Merge a bunch of small articles about system tables into single one * Merge a bunch of small articles about formats into single one * Adapt table with formats to English docs too * Add SPb meetup link to main page * Move Utilities out of top level of docs (the location is probably not yet final) + translate couple articles * Merge MacOS.md into build_osx.md * Move Data types higher in ToC * Publish changelog on website alongside documentation * Few fixes for en/table_engines/file.md * Use smaller header sizes in changelogs * Group up table engines inside ToC * Move table engines out of top level too * Specificy in ToC that query language is SQL based. Thats a bit excessive, but catches eye. * Move stuff that is part of query language into respective folder * Move table functions lower in ToC * Lost redirects.txt update * Do not rely on comments in yaml + fix few ru titles * Extract major parts of queries.md into separate articles * queries.md has been supposed to be removed * Fix weird translation * Fix a bunch of links * There is only table of contents left * "Query language" is actually part of SQL abbreviation * Change filename in README.md too * fix mistype
4.0 KiB
How to contribute to ClickHouse documentation?
Basically ClickHouse uses "documentation as code" approach, so you can edit Markdown files in this folder from GitHub web interface or fork ClickHouse repository, edit, commit, push and open pull request.
At the moment documentation is bilingual in English and Russian, so it's better to try keeping languages in sync if you can, but it's not strictly required as there are people watching over this. If you add new article, you should also add it to toc_{en,ru}.yaml file with pages index.
Master branch is then asynchronously published to ClickHouse official website:
- In English: https://clickhouse.yandex/docs/en/
- In Russian: https://clickhouse.yandex/docs/ru/
Infrastructure to build Markdown to documentation website resides in tools folder, it has it's own README.md with more details.
How to write content for ClickHouse documentation?
Target audience
When you write pretty much any text, first thing you should think about: who exactly will read it and in which terms it is better to "talk" with them.
ClickHouse can be directly used by all sorts of either analysts and engineers, so you should only basic technical background of reader when writing content for generic parts of documentation, like query language, tutorials or overviews. Though it is ok for articles describing ClickHouse internals, guides for operating ClickHouse clusters, contributing to C++ code and other similar topics.
Specific recommendations
- Documentation should make sense when you read it roughly from start to end. So when choosing a place for new content try to minimize referring to stuff that will be described later on.
- If documentation section consists of many similar items, like functions or operators, try to order them from more generic (usable by wider audience) to more specific (to some usecases or application types). If several items are intended to be mostly used together, keep them together in documentation too.
- Try to avoid slang, use the most common and specific terms for everythings. If some terms are used as synonyms, state this explicitly.
- All functionality descriptions should be accompanied by examples. At least very basic ones, but real world examples are welcome too.
- Debatable topics like politics, religion, racial and so on are strictly prohibited in either documentation, examples, comments and code.
- People tend to get temporary stuck with some specific words or phrases, usually auxiliary, for a shord period of time. So they get repeated over and over in small part of content, which looks weird when reading. It is easy to fix this by reading your text again before publishing, also you can use this opportunity to fix mistypes and lost punctuation.
- Try to avoid naming the reader in text, it is not strictly prohibited though.
Quick cheatsheet on used Markdown dialect
- Headers on separate line starting with
#,##or###. - Bold is in
**asterisks**or__underlines__. - Links
[anchor](http://...), images. - Lists are on lines starting with
* unorderedor1. ordered, but there should be empty line before first list item. Sub-lists must be indented with 4 spaces. - Inline piece of code is
`in backticks`. - Multiline code block are
```in triple backtick quotes ```. - Brightly highlighted block of text starts with
!!! info "Header", on next line 4 spaces and content. Instead ofinfocan bewarning. - Hide block to be opened by click:
<details> <summary>Header</summary> hidden content</details>. - Colored text:
<span style="color: red;">text</span>. - Additional anchor to be linked to:
<a name="my_anchor"></a>, for headers fully in English they are created automatically like"FoO Bar" -> "foo-bar". - Table:
| Header 1 | Header 2 | Header 3 |
| ----------- | ----------- | ----------- |
| Cell A1 | Cell A2 | Cell A3 |
| Cell B1 | Cell B2 | Cell B3 |
| Cell C1 | Cell C2 | Cell C3 |