[hotfix] Refresh Slack invite link
[flink-web.git] / contributing / docs-style.md
index a7c79be08eeb3204f5154972fcc9e592e6de6714..08dbef7b162221a7d72b18a97297097a918bcb0b 100644 (file)
@@ -68,12 +68,21 @@ Principles](#general-guiding-principles).
   struggling to complete an action, using words like _quick_ or _easy_ can lead
   to a poor documentation experience.
 
+* **Avoid using uppercase words** to highlight or emphasize statements.
+  Highlighting key words with e.g. **bold** or _italic_ font usually appears more polite.
+  If you want to draw attention to important but not obvious statements,
+  try to group them into separate paragraphs starting with a label,
+  highlighted with a corresponding HTML tag:
+  * `<span class="label label-info">Note</span>`
+  * `<span class="label label-warning">Warning</span>`
+  * `<span class="label label-danger">Danger</span>`
+
 ### Using Flink-specific Terms
 
 Use clear definitions of terms or provide additional instructions on what
 something means by adding a link to a helpful resource, such as other
 documentation pages or the [Flink
-Glossary](https://ci.apache.org/projects/flink/flink-docs-master/concepts/glossary.html).
+Glossary]({{site.DOCS_BASE_URL}}flink-docs-stable/docs/concepts/glossary).
 The Glossary is a work in progress, so you can also propose new terms by
 opening a pull-request.
 
@@ -82,7 +91,7 @@ opening a pull-request.
 ## Repository
 
 Markdown files (.md) should have a short name that summarizes the topic
-covered, spelled in **lowercase** and with **underscores** separating the
+covered, spelled in **lowercase** and with **dashes (-)** separating the
 words. The Chinese version file should have the same name as the English
 version, but suffixed with **.zh.md**.
 
@@ -454,6 +463,32 @@ Or using plain HTML:
     might not be obvious from reading it. Use comments to clarify
     implementation details and to describe the expected output.
 
+* **Commands in code blocks.** Commands can be documented using `bash` syntax 
+  highlighted code blocks. The following items should be considered when adding 
+  commands to the docummentation:
+  * **Use long parameter names.** Long parameter names help the reader to 
+    understand the purpose of the command. They should be preferred over their 
+    short counterparts.
+  * **One parameter per line.** Using long parameter names makes the command 
+    possibly harder to read. Putting one parameter per line improves the 
+    readability. You need to add a backslash `\` escaping the newline at 
+    the end of each intermediate line to support copy&paste.
+  * **Indentation**. Each new parameter line should be indented by 6 spaces.
+  * **Use `$` prefix to indicate command start**. The readability of the code 
+    block might worsen having multiple commands in place. Putting a dollar sign 
+    `$` in front of each new commands helps identifying the start of a 
+    command.
+
+  A properly formatted command would look like this:
+
+  ```bash
+$ ./bin/flink run-application \
+        --target kubernetes-application \
+        -Dkubernetes.cluster-id=my-first-application-cluster \
+        -Dkubernetes.container.image=custom-image-name \
+        local:///opt/flink/usrlib/my-flink-job.jar
+  ```
+
 [Back to top](#top)
 
 ## General Guiding Principles