This guide provides an overview of the essential style guidelines for writing and contributing to the Flink documentation. It's meant to support your contribution journey in the greater community effort to improve and extend existing documentation — and help make it more accessible, consistent and inclusive.
{% toc %}
The Flink documentation is maintained in US English and Chinese — when extending or updating the documentation, both versions should be addressed in one pull request. If you are not familiar with the Chinese language, make sure that your contribution is complemented by these additional steps:
Looking for style guides to contribute with translating existing documentation to Chinese? Go ahead and consult this translation specification.
Below, you find some basic guidelines that can help ensure readability and accessibility in your writing. For a deeper and more complete dive into language style, also refer to the General Guiding Principles.
Use active voice. Active voice supports brevity and makes content more engaging. If you add by zombies after the verb in a sentence and it still makes sense, you are using the passive voice.
Passive Voice
Use you, never we. Using we can be confusing and patronizing to some users, giving the impression that “we are all members of a secret club and you didn’t get a membership invite”. Address the user as you.
Avoid gender- and culture-specific language. There is no need to identify gender in documentation: technical writing should be gender-neutral. Also, jargon and conventions that you take for granted in your own language or culture are often different elsewhere. Humor is a staple example: a great joke in one culture can be widely misinterpreted in another.
Avoid qualifying and prejudging actions. For a user that is frustrated or struggling to complete an action, using words like quick or easy can lead to a poor documentation experience.
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. The Glossary is a work in progress, so you can also propose new terms by opening a pull-request.
Markdown files (.md) should have a short name that summarizes the topic covered, spelled in lowercase and with underscores separating the words. The Chinese version file should have the same name as the English version, but suffixed with .zh.md.
The documentation website is generated using Jekyll and the pages are written in Markdown, a lightweight portable format for web publishing (but not limited to it).
Markdown can also be used in combination with GitHub Flavored Markdown and plain HTML. For example, some contributors prefer to use HTML tags for images and are free to do so with this intermix.
In addition to Markdown, each file contains a YAML front matter block that will be used to set variables and metadata on the page. The front matter must be the first thing in the file and must be specified as a valid YAML set between triple-dashed lines.
--- title: Concepts layout: redirect --- <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
Below are the front matter variables most commonly used along the Flink documentation.
Documentation-wide information and configuration settings that sit under _config.yml
are also available to the front matter through the site variable. These settings can be accessed using the following syntax:
{{ "{{ site.CONFIG_KEY " }}}}
The placeholder will be replaced with the value of the variable named CONFIG_KEY
when generating the documentation.
Listed in the following sections are the basic formatting guidelines to get you started with writing documentation that is consistent and simple to navigate.
In Markdown, headings are any line prefixed with a hash (#), with the number of hashes indicating the level of the heading. Headings should be nested and consecutive — never skip a header level for styling reasons!
Use descriptive language in the phrasing of headings. For example, for a documentation page on dynamic tables, “Dynamic Tables and Continuous Queries” is more descriptive than “Background” or “Technical Information”.
In the documentation build, the Table Of Contents (TOC) is automatically generated from the headings of the page using the following line of markup:
{{ "{:toc" }}}
All headings up to Level-3 are considered. To exclude a particular heading from the TOC:
{{ "# Excluded Heading {:.no_toc" }}}
Write a short and concise introduction to the topic that is being covered and place it before the TOC. A little context, such an outline of key messages, goes a long way in ensuring that the documentation is consistent and accessible to all levels of knowledge.
In the documentation build, navigation is defined using properties configured in the front-matter variables of each page.
It's possible to use Back to Top links in extensive documentation pages, so that users can navigate to the top of the page without having to scroll back up manually. In markup, this is implemented as a placeholder that is replaced with a default link when generating the documentation:
{{ "{% top " }}%}
It's recommended to use Back to Top links at least at the end of each Level-2 section.
In case you want to include edge cases, tightly related information or nice-to-knows in the documentation, it’s a (very) good practice to highlight them using special annotations.
To highlight a tip or piece of information that may be helpful to know:
<div class="alert alert-info"> // Info Message </div>
To signal danger of pitfalls or call attention to an important piece of information that is crucial to follow:
<div class="alert alert-danger"> // Danger Message </div>
Adding links to documentation is an effective way to guide the user into a better understanding of the topic being discussed without the risk of overwriting.
Links to sections in the page. Each heading generates an implicit identifier to directly link it within a page. This identifier is generated by making the heading lowercase and replacing internal spaces with hyphens.
[Link Text](#heading-title)
Links to other pages of the Flink documentation. The base relative path to the domain of the documentation is available as a configuration variable named baseurl
.
{% raw %}
[Link Text]({{ site.baseurl }}{% link path/to/link-page.md %})
{% endraw %}
Links to external pages
[Link Text](external_url)
Use descriptive links that provide information on the action or destination. For example, avoid using “Learn More” or “Click Here” links.
Figures and other visual elements are placed under the root fig folder and can be referenced in documentation pages using a syntax similar to that of links:
![Picture Text]({{ "{{ site.baseurl " }}}}/fig/image_name.png){:height="200px" width="200px"}
Or using plain HTML:
{% highlight html %} {% endhighlight %}
Use flowcharts, tables and figures where appropriate or necessary for additional clarification, but never as a standalone source of information. Make sure that any text included in those elements is large enough to read and that the overall resolution is adequate.
Inline code. Small code snippets or references to language constructs in normal text flow should be highlighted using surrounding backticks ( ` ).
Code blocks. Code that represents self-contained examples, feature walkthroughs, demonstration of best practices or other useful scenarios should be wrapped using a fenced code block with appropriate syntax highlighting. One way of achieving this with markup is:
{{ "{% highlight java"}}%} // Java Code {{"{% endhighlight"}}%}
which is equivalent to using triple backticks ( ``` ):
```java // Java Code ```
When specifying multiple programming languages, each code block should be styled as a tab:
<div class="codetabs" markdown="1"> <div data-lang="java" markdown="1"> {{ "{% highlight java"}}%} // Java Code {{"{% endhighlight"}}%} </div> <div data-lang="scala" markdown="1"> {{ "{% highlight scala"}}%} // Scala Code {{"{% endhighlight"}}%} </div> </div>
These code blocks are often used to learn and explore, so there are a few best practices to keep in mind:
Showcase key development tasks. Reserve code examples for common implementation scenarios that are meaningful for users. Leave more lengthy and complicated examples for tutorials or walkthroughs.
Ensure the code is standalone. Code examples should be self-contained and not have external dependencies (except for outlier cases such as examples on how to use specific connectors). Include all import statements without using wildcards, so that newcomers can understand and learn which packages are being used.
Avoid shortcuts. For example, handle exceptions and cleanup as you would in real-world code.
Include comments, but don’t overdo it. Provide an introduction describing the main functionality of the code and possible caveats that might not be obvious from reading it. Use comments to clarify implementation details and to describe the expected output.
This style guide has the overarching goal of setting the foundation for documentation that is Accessible, Consistent, Objective, Logical and Inclusive.
The Flink community is diverse and international, so you need to think wide and globally when writing documentation. Not everyone speaks English at a native level and the level of experience with Flink (and stream processing in general) ranges from absolute beginners to experienced advanced users. Ensure technical accuracy and linguistic clarity in the content you produce so that it can be understood by all users.
Stick to the basic guidelines detailed in this style guide and use your own best judgment to uniformly spell, capitalize, hyphenate, bold and italicize text. Correct grammar, punctuation and spelling are desirable, but not a hard requirement — documentation contributions are open to any level of language proficiency.
Keep your sentences short and to the point. As a rule of thumb, if a sentence is shorter than 14 words, readers will likely understand 90 percent of its content. Sentences with more than 25 words are usually harder to understand and should be revised and split, when possible. Being concise and using well-known keywords also allows users to navigate to relevant documentation with little effort.
Be mindful that most users will scan through online content and only read around 28 percent of it. This underscores the importance of grouping related ideas together into a clear hierarchy of information and using focused, descriptive headings. Placing the most relevant information in the first two paragraphs of each section is a good practice that increases the “return of time invested” for the user.
Use positive language and concrete, relatable examples to ensure the content is findable and welcoming to all users. The documentation is translated to other languages, so using simple language and familiar words also helps reduce the translation effort.