Google Git
Sign in
apache / flink-web / 985d9da79fab248e5746d64ee6700f870acb5270 / . / content / contributing / docs-style.html
blob: 5c96a82bc5b0b74a08603948b2ed1529a40fbcbf [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<!-- The above 3 meta tags *must* come first in the head; any other head content must come *after* these tags -->
<title>Apache Flink: Documentation Style Guide</title>
<link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
<link rel="icon" href="/favicon.ico" type="image/x-icon">
<!-- Bootstrap -->
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.4.1/css/bootstrap.min.css">
<link rel="stylesheet" href="/css/flink.css">
<link rel="stylesheet" href="/css/syntax.css">
<!-- Blog RSS feed -->
<link href="/blog/feed.xml" rel="alternate" type="application/rss+xml" title="Apache Flink Blog: RSS feed" />
<!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
<!-- We need to load Jquery in the header for custom google analytics event tracking-->
<script src="/js/jquery.min.js"></script>
<!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
<!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
</head>
<body>
<!-- Main content. -->
<div class="container">
<div class="row">
<div id="sidebar" class="col-sm-3">
<!-- Top navbar. -->
<nav class="navbar navbar-default">
<!-- The logo. -->
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<div class="navbar-logo">
<a href="/">
<img alt="Apache Flink" src="/img/flink-header-logo.svg" width="147px" height="73px">
</a>
</div>
</div><!-- /.navbar-header -->
<!-- The navigation links. -->
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<ul class="nav navbar-nav navbar-main">
<!-- First menu section explains visitors what Flink is -->
<!-- What is Stream Processing? -->
<!--
<li><a href="/streamprocessing1.html">What is Stream Processing?</a></li>
-->
<!-- What is Flink? -->
<li><a href="/flink-architecture.html">What is Apache Flink?</a></li>
<!-- What is Stateful Functions? -->
<li><a href="/stateful-functions.html">What is Stateful Functions?</a></li>
<!-- Use cases -->
<li><a href="/usecases.html">Use Cases</a></li>
<!-- Powered by -->
<li><a href="/poweredby.html">Powered By</a></li>
&nbsp;
<!-- Second menu section aims to support Flink users -->
<!-- Downloads -->
<li><a href="/downloads.html">Downloads</a></li>
<!-- Getting Started -->
<li class="dropdown">
<a class="dropdown-toggle" data-toggle="dropdown" href="#">Getting Started<span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a href="https://ci.apache.org/projects/flink/flink-docs-release-1.10/getting-started/index.html" target="_blank">With Flink <small><span class="glyphicon glyphicon-new-window"></span></small></a></li>
<li><a href="https://ci.apache.org/projects/flink/flink-statefun-docs-release-2.1/getting-started/project-setup.html" target="_blank">With Flink Stateful Functions <small><span class="glyphicon glyphicon-new-window"></span></small></a></li>
<li><a href="/training.html">Training Course</a></li>
</ul>
</li>
<!-- Documentation -->
<li class="dropdown">
<a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation<span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a href="https://ci.apache.org/projects/flink/flink-docs-release-1.10" target="_blank">Flink 1.10 (Latest stable release) <small><span class="glyphicon glyphicon-new-window"></span></small></a></li>
<li><a href="https://ci.apache.org/projects/flink/flink-docs-master" target="_blank">Flink Master (Latest Snapshot) <small><span class="glyphicon glyphicon-new-window"></span></small></a></li>
<li><a href="https://ci.apache.org/projects/flink/flink-statefun-docs-release-2.1" target="_blank">Flink Stateful Functions 2.1 (Latest stable release) <small><span class="glyphicon glyphicon-new-window"></span></small></a></li>
<li><a href="https://ci.apache.org/projects/flink/flink-statefun-docs-master" target="_blank">Flink Stateful Functions Master (Latest Snapshot) <small><span class="glyphicon glyphicon-new-window"></span></small></a></li>
</ul>
</li>
<!-- getting help -->
<li><a href="/gettinghelp.html">Getting Help</a></li>
<!-- Blog -->
<li><a href="/blog/"><b>Flink Blog</b></a></li>
<!-- Flink-packages -->
<li>
<a href="https://flink-packages.org" target="_blank">flink-packages.org <small><span class="glyphicon glyphicon-new-window"></span></small></a>
</li>
&nbsp;
<!-- Third menu section aim to support community and contributors -->
<!-- Community -->
<li><a href="/community.html">Community &amp; Project Info</a></li>
<!-- Roadmap -->
<li><a href="/roadmap.html">Roadmap</a></li>
<!-- Contribute -->
<li><a href="/contributing/how-to-contribute.html">How to Contribute</a></li>
<ul class="nav navbar-nav navbar-subnav">
<li >
<a href="/contributing/contribute-code.html">Contribute Code</a>
</li>
<li >
<a href="/contributing/reviewing-prs.html">Review Pull Requests</a>
</li>
<li >
<a href="/contributing/code-style-and-quality-preamble.html">Code Style and Quality Guide</a>
</li>
<li >
<a href="/contributing/contribute-documentation.html">Contribute Documentation</a>
</li>
<li class="active">
<a href="/contributing/docs-style.html">Documentation Style Guide</a>
</li>
<li >
<a href="/contributing/improve-website.html">Contribute to the Website</a>
</li>
</ul>
<!-- GitHub -->
<li>
<a href="https://github.com/apache/flink" target="_blank">Flink on GitHub <small><span class="glyphicon glyphicon-new-window"></span></small></a>
</li>
&nbsp;
<!-- Language Switcher -->
<li>
<a href="/zh/contributing/docs-style.html">中文版</a>
</li>
</ul>
<ul class="nav navbar-nav navbar-bottom">
<hr />
<!-- Twitter -->
<li><a href="https://twitter.com/apacheflink" target="_blank">@ApacheFlink <small><span class="glyphicon glyphicon-new-window"></span></small></a></li>
<!-- Visualizer -->
<li class=" hidden-md hidden-sm"><a href="/visualizer/" target="_blank">Plan Visualizer <small><span class="glyphicon glyphicon-new-window"></span></small></a></li>
<hr />
<li><a href="https://apache.org" target="_blank">Apache Software Foundation <small><span class="glyphicon glyphicon-new-window"></span></small></a></li>
<li>
<style>
.smalllinks:link {
display: inline-block !important; background: none; padding-top: 0px; padding-bottom: 0px; padding-right: 0px; min-width: 75px;
}
</style>
<a class="smalllinks" href="https://www.apache.org/licenses/" target="_blank">License</a> <small><span class="glyphicon glyphicon-new-window"></span></small>
<a class="smalllinks" href="https://www.apache.org/security/" target="_blank">Security</a> <small><span class="glyphicon glyphicon-new-window"></span></small>
<a class="smalllinks" href="https://www.apache.org/foundation/sponsorship.html" target="_blank">Donate</a> <small><span class="glyphicon glyphicon-new-window"></span></small>
<a class="smalllinks" href="https://www.apache.org/foundation/thanks.html" target="_blank">Thanks</a> <small><span class="glyphicon glyphicon-new-window"></span></small>
</li>
</ul>
</div><!-- /.navbar-collapse -->
</nav>
</div>
<div class="col-sm-9">
<div class="row-fluid">
<div class="col-sm-12">
<h1>Documentation Style Guide</h1>
<p>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 <strong>accessible</strong>, <strong>consistent</strong>
and <strong>inclusive</strong>.</p>
<div class="page-toc">
<ul id="markdown-toc">
<li><a href="#language" id="markdown-toc-language">Language</a></li>
<li><a href="#language-style" id="markdown-toc-language-style">Language Style</a> <ul>
<li><a href="#voice-and-tone" id="markdown-toc-voice-and-tone">Voice and Tone</a></li>
<li><a href="#using-flink-specific-terms" id="markdown-toc-using-flink-specific-terms">Using Flink-specific Terms</a></li>
</ul>
</li>
<li><a href="#repository" id="markdown-toc-repository">Repository</a></li>
<li><a href="#syntax" id="markdown-toc-syntax">Syntax</a> <ul>
<li><a href="#extended-syntax" id="markdown-toc-extended-syntax">Extended Syntax</a></li>
<li><a href="#front-matter" id="markdown-toc-front-matter">Front Matter</a></li>
</ul>
</li>
<li><a href="#formatting" id="markdown-toc-formatting">Formatting</a> <ul>
<li><a href="#headings" id="markdown-toc-headings">Headings</a></li>
<li><a href="#table-of-contents" id="markdown-toc-table-of-contents">Table of Contents</a></li>
<li><a href="#navigation" id="markdown-toc-navigation">Navigation</a></li>
<li><a href="#annotations" id="markdown-toc-annotations">Annotations</a></li>
<li><a href="#links" id="markdown-toc-links">Links</a></li>
<li><a href="#visual-elements" id="markdown-toc-visual-elements">Visual Elements</a></li>
<li><a href="#code" id="markdown-toc-code">Code</a></li>
</ul>
</li>
<li><a href="#general-guiding-principles" id="markdown-toc-general-guiding-principles">General Guiding Principles</a></li>
</ul>
</div>
<h2 id="language">Language</h2>
<p>The Flink documentation is maintained in <strong>US English</strong> and <strong>Chinese</strong> — 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:</p>
<ul>
<li>Open a
<a href="https://issues.apache.org/jira/projects/FLINK/issues/FLINK-12070?filter=allopenissues">JIRA</a>
ticket for the translation, tagged with the chinese-translation component;</li>
<li>Link the ticket to the original contribution JIRA ticket.</li>
</ul>
<p>Looking for style guides to contribute with translating existing documentation
to Chinese? Go ahead and consult <a href="https://cwiki.apache.org/confluence/display/FLINK/Flink+Translation+Specifications">this translation
specification</a>.</p>
<p><a href="#top">Back to top</a></p>
<h2 id="language-style">Language Style</h2>
<p>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 <a href="#general-guiding-principles">General Guiding
Principles</a>.</p>
<h3 id="voice-and-tone">Voice and Tone</h3>
<ul>
<li>
<p><strong>Use active voice.</strong> <a href="https://medium.com/@DaphneWatson/technical-writing-active-vs-passive-voice-485dfaa4e498">Active
voice</a>
supports brevity and makes content more engaging. If you add <em>by zombies</em>
after the verb in a sentence and it still makes sense, you are using the
passive voice.</p>
<div class="alert alert-info">
<b>Active Voice</b>
<p>"You can run this example in your IDE or on the command line."</p>
<p></p>
<b>Passive Voice</b>
<p>"This example can be run in your IDE or on the command line (by zombies)."</p>
</div>
</li>
<li>
<p><strong>Use you, never we.</strong> Using <em>we</em> can be confusing and patronizing to some
users, giving the impression that “we are all members of a secret club and
<em>you</em> didn’t get a membership invite”. Address the user as <em>you</em>.</p>
</li>
<li>
<p><strong>Avoid gender- and culture-specific language.</strong> There is no need to identify
gender in documentation: technical writing should be
<a href="https://techwhirl.com/gender-neutral-technical-writing/">gender-neutral</a>.
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.</p>
</li>
<li>
<p><strong>Avoid qualifying and prejudging actions.</strong> For a user that is frustrated or
struggling to complete an action, using words like <em>quick</em> or <em>easy</em> can lead
to a poor documentation experience.</p>
</li>
</ul>
<h3 id="using-flink-specific-terms">Using Flink-specific Terms</h3>
<p>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 <a href="https://ci.apache.org/projects/flink/flink-docs-master/concepts/glossary.html">Flink
Glossary</a>.
The Glossary is a work in progress, so you can also propose new terms by
opening a pull-request.</p>
<p><a href="#top">Back to top</a></p>
<h2 id="repository">Repository</h2>
<p>Markdown files (.md) should have a short name that summarizes the topic
covered, spelled in <strong>lowercase</strong> and with <strong>underscores</strong> separating the
words. The Chinese version file should have the same name as the English
version, but suffixed with <strong>.zh.md</strong>.</p>
<p><a href="#top">Back to top</a></p>
<h2 id="syntax">Syntax</h2>
<p>The documentation website is generated using
<a href="https://jekyllrb.com/docs/">Jekyll</a> and the pages are written in
<a href="https://daringfireball.net/projects/markdown/syntax">Markdown</a>, a lightweight
portable format for web publishing (but not limited to it).</p>
<h3 id="extended-syntax">Extended Syntax</h3>
<p>Markdown can also be used in combination with <a href="https://guides.github.com/features/mastering-markdown/">GitHub Flavored
Markdown</a> and plain
<a href="http://www.simplehtmlguide.com/cheatsheet.php">HTML</a>. For example, some
contributors prefer to use HTML tags for images and are free to do so with this
intermix.</p>
<h3 id="front-matter">Front Matter</h3>
<p>In addition to Markdown, each file contains a YAML <a href="https://jekyllrb.com/docs/front-matter/">front matter
block</a> 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.</p>
<div class="alert alert-warning">
<h3>Apache License</h3>
<p>For every documentation file, the front matter should be immediately
followed by the Apache License statement. For both language versions, this
block must be stated in US English and copied in the exact same words as in
the following example.</p>
</div>
<div class="highlight"><pre><code>---
title: Concepts
layout: redirect
---
&lt;!--
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.
--&gt;
</code></pre></div>
<p>Below are the front matter variables most commonly used along the Flink
documentation.</p>
<font size="3">
<table width="100%" class="table table-bordered">
<thead>
<tr>
<th></th>
<th style="vertical-align : middle;"><center><b>Variable</b></center></th>
<th style="vertical-align : middle;"><center><b>Possible Values</b></center></th>
<th style="vertical-align : middle;"><center><b>Description</b></center></th>
</tr>
<tr>
<td><b>Layout</b></td>
<td>layout</td>
<td>{base,plain,redirect}</td>
<td>The layout file to use. Layout files are located under the <i>_layouts</i> directory.</td>
</tr>
<tr>
<td><b>Content</b></td>
<td>title</td>
<td>%s</td>
<td>The title to be used as the top-level (Level-1) heading for the page.</td>
</tr>
<tr>
<td rowspan="4" style="vertical-align : middle;"><b>Navigation</b></td>
<td>nav-id</td>
<td>%s</td>
<td>The ID of the page. Other pages can use this ID as their nav-parent_id.</td>
</tr>
<tr>
<td>nav-parent_id</td>
<td>{root,%s}</td>
<td>The ID of the parent page. The lowest navigation level is root.</td>
</tr>
<tr>
<td>nav-pos</td>
<td>%d</td>
<td>The relative position of pages per navigation level.</td>
</tr>
<tr>
<td>nav-title</td>
<td>%s</td>
<td>The title to use as an override of the default link text (title).</td>
</tr>
</thead>
</table>
</font>
<p>Documentation-wide information and configuration settings that sit under
<code>_config.yml</code> are also available to the front matter through the site variable.
These settings can be accessed using the following syntax:</p>
<div class="highlight"><pre><code class="language-liquid"><span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">CONFIG_KEY</span><span class="w"> </span><span class="p">}}</span></code></pre></div>
<p>The placeholder will be replaced with the value of the variable named <code>CONFIG_KEY</code> when generating the documentation.</p>
<p><a href="#top">Back to top</a></p>
<h2 id="formatting">Formatting</h2>
<p>Listed in the following sections are the basic formatting guidelines to get you
started with writing documentation that is consistent and simple to navigate.</p>
<h3 id="headings">Headings</h3>
<p>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!</p>
<font size="3">
<table width="100%" class="table table-bordered">
<thead>
<tr>
<th style="vertical-align : middle;"><center><b>Syntax</b></center></th>
<th style="vertical-align : middle;"><center><b>Level</b></center></th>
<th style="vertical-align : middle;"><center><b>Description</b></center></th>
</tr>
<tr>
<td># Heading</td>
<td><center>Level-1</center></td>
<td>The page title is defined in the Front Matter, so this level should <b>not be used</b>.</td>
</tr>
<tr>
<td>## Heading</td>
<td><center>Level-2</center></td>
<td>Starting level for Sections. Used to organize content by higher-level topics or goals.</td>
</tr>
<tr>
<td>### Heading</td>
<td><center>Level-3</center></td>
<td rowspan="2" style="vertical-align : middle;">Sub-sections. Used in each Section to separate supporting information or tasks.</td>
</tr>
<tr>
<td>#### Heading</td>
<td><center>Level-4</center></td>
</tr>
</thead>
</table>
</font>
<div class="alert alert-warning">
<h3>Best Practice</h3>
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".
</div>
<h3 id="table-of-contents">Table of Contents</h3>
<p>In the documentation build, the <strong>Table Of Contents</strong> (TOC) is automatically
generated from the headings of the page using the following line of markup:</p>
<div class="highlight"><pre><code class="language-liquid">{:toc}</code></pre></div>
<p>All headings up to <strong>Level-3</strong> are considered. To exclude a particular heading
from the TOC:</p>
<div class="highlight"><pre><code class="language-liquid"># Excluded Heading
{:.no_toc}</code></pre></div>
<div class="alert alert-warning">
<h3>Best Practice</h3>
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.
</div>
<h3 id="navigation">Navigation</h3>
<p>In the documentation build, navigation is defined using properties configured
in the <a href="#front-matter">front-matter variables</a> of each page.</p>
<p>It’s possible to use <em>Back to Top</em> 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:</p>
<div class="highlight"><pre><code class="language-liquid"><span class="p">{%</span><span class="w"> </span><span class="nt">top</span><span class="w"> </span><span class="p">%}</span></code></pre></div>
<div class="alert alert-warning">
<h3>Best Practice</h3>
It's recommended to use Back to Top links at least at the end of each Level-2
section.
</div>
<h3 id="annotations">Annotations</h3>
<p>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.</p>
<ul>
<li>
<p>To highlight a tip or piece of information that may be helpful to know:</p>
<div class="highlight"><pre><code class="language-html"><span class="nt">&lt;div</span> <span class="na">class=</span><span class="s">&quot;alert alert-info&quot;</span><span class="nt">&gt;</span> // Info Message <span class="nt">&lt;/div&gt;</span></code></pre></div>
</li>
<li>
<p>To signal danger of pitfalls or call attention to an important piece of
information that is crucial to follow:</p>
<div class="highlight"><pre><code class="language-html"><span class="nt">&lt;div</span> <span class="na">class=</span><span class="s">&quot;alert alert-danger&quot;</span><span class="nt">&gt;</span> // Danger Message <span class="nt">&lt;/div&gt;</span></code></pre></div>
</li>
</ul>
<h3 id="links">Links</h3>
<p>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.</p>
<ul>
<li>
<p><strong>Links to sections in the page.</strong> 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.</p>
<ul>
<li><strong>Heading:</strong> ## Heading Title</li>
<li><strong>ID:</strong> #heading-title</li>
</ul>
<p></p>
<div class="highlight"><pre><code class="language-liquid">[Link Text](#heading-title)</code></pre></div>
</li>
<li>
<p><strong>Links to other pages of the Flink documentation.</strong></p>
<div class="highlight"><pre><code class="language-liquid">[Link Text](<span class="p">{%</span><span class="w"> </span><span class="nt">link</span><span class="w"> </span>path/to/link-page.md<span class="w"> </span><span class="p">%}</span>)</code></pre></div>
</li>
<li>
<p><strong>Links to external pages</strong></p>
<div class="highlight"><pre><code class="language-liquid">[Link Text](external_url)</code></pre></div>
</li>
</ul>
<div class="alert alert-warning">
<h3>Best Practice</h3>
Use descriptive links that provide information on the action or destination.
For example, avoid using "Learn More" or "Click Here" links.
</div>
<h3 id="visual-elements">Visual Elements</h3>
<p>Figures and other visual elements are placed under the root <em>fig</em> folder and
can be referenced in documentation pages using a syntax similar to that of
links:</p>
<div class="highlight"><pre><code class="language-liquid">![Picture Text](<span class="p">{{</span><span class="w"> </span><span class="nv">site</span><span class="p">.</span><span class="nv">baseurl</span><span class="w"> </span><span class="p">}}</span>/fig/image_name.png){:height=&quot;200px&quot; width=&quot;200px&quot;}</code></pre></div>
<p>Or using plain HTML:</p>
<figure class="highlight"><pre><code class="language-html" data-lang="html"><span class="nt">&lt;img</span> <span class="na">src=</span><span class="s">&quot;/fig/image_name.png&quot;</span> <span class="na">class=</span><span class="s">&quot;center&quot;</span> <span class="na">height=</span><span class="s">&quot;200px&quot;</span> <span class="na">width=</span><span class="s">&quot;200px&quot;</span><span class="nt">/&gt;</span></code></pre></figure>
<div class="alert alert-warning">
<h3>Best Practice</h3>
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.
</div>
<h3 id="code">Code</h3>
<ul>
<li>
<p><strong>Inline code.</strong> Small code snippets or references to language constructs in
normal text flow should be highlighted using surrounding backticks ( <strong>`</strong>
).</p>
</li>
<li>
<p><strong>Code blocks.</strong> 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 <a href="https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers">syntax
highlighting</a>.
One way of achieving this with markup is:</p>
<div class="highlight"><pre><code class="language-liquid"><span class="p">{%</span><span class="w"> </span><span class="nt">highlight</span><span class="w"> </span>java<span class="p">%}</span>
// Java Code
<span class="p">{%</span><span class="w"> </span><span class="nt">endhighlight</span><span class="p">%}</span></code></pre></div>
<p>which is equivalent to using triple backticks ( <strong>```</strong> ):</p>
<div class="highlight"><pre><code class="language-liquid">```java
// Java Code
```</code></pre></div>
<p>When specifying multiple programming languages, each code block should be styled as a tab:</p>
<div class="highlight"><pre><code class="language-html"><span class="nt">&lt;div</span> <span class="na">class=</span><span class="s">&quot;codetabs&quot;</span> <span class="na">markdown=</span><span class="s">&quot;1&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;div</span> <span class="na">data-lang=</span><span class="s">&quot;java&quot;</span> <span class="na">markdown=</span><span class="s">&quot;1&quot;</span><span class="nt">&gt;</span>
{% highlight java%}
// Java Code
{% endhighlight%}
<span class="nt">&lt;/div&gt;</span>
<span class="nt">&lt;div</span> <span class="na">data-lang=</span><span class="s">&quot;scala&quot;</span> <span class="na">markdown=</span><span class="s">&quot;1&quot;</span><span class="nt">&gt;</span>
{% highlight scala%}
// Scala Code
{% endhighlight%}
<span class="nt">&lt;/div&gt;</span>
<span class="nt">&lt;/div&gt;</span></code></pre></div>
<p>These code blocks are often used to learn and explore, so there are a few
best practices to keep in mind:</p>
<ul>
<li>
<p><strong>Showcase key development tasks.</strong> Reserve code examples for common
implementation scenarios that are meaningful for users. Leave more lengthy
and complicated examples for tutorials or walkthroughs.</p>
</li>
<li>
<p><strong>Ensure the code is standalone.</strong> 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.</p>
</li>
<li>
<p><strong>Avoid shortcuts.</strong> For example, handle exceptions and cleanup as you
would in real-world code.</p>
</li>
<li>
<p><strong>Include comments, but don’t overdo it.</strong> 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.</p>
</li>
</ul>
</li>
</ul>
<p><a href="#top">Back to top</a></p>
<h2 id="general-guiding-principles">General Guiding Principles</h2>
<p>This style guide has the overarching goal of setting the foundation for
documentation that is <strong>Accessible</strong>, <strong>Consistent</strong>, <strong>Objective</strong>,
<strong>Logical</strong> and <strong>Inclusive</strong>.</p>
<h4 id="accessible">Accessible</h4>
<p>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.</p>
<h4 id="consistent">Consistent</h4>
<p>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.</p>
<h4 id="objective">Objective</h4>
<p>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.</p>
<h4 id="logical">Logical</h4>
<p>Be mindful that most users will scan through online content and only read
around <a href="https://www.nngroup.com/articles/website-reading/">28 percent of it</a>.
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.</p>
<h4 id="inclusive">Inclusive</h4>
<p>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.</p>
</div>
</div>
</div>
</div>
<hr />
<div class="row">
<div class="footer text-center col-sm-12">
<p>Copyright © 2014-2019 <a href="http://apache.org">The Apache Software Foundation</a>. All Rights Reserved.</p>
<p>Apache Flink, Flink®, Apache®, the squirrel logo, and the Apache feather logo are either registered trademarks or trademarks of The Apache Software Foundation.</p>
<p><a href="/privacy-policy.html">Privacy Policy</a> &middot; <a href="/blog/feed.xml">RSS feed</a></p>
</div>
</div>
</div><!-- /.container -->
<!-- Include all compiled plugins (below), or include individual files as needed -->
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.matchHeight/0.7.0/jquery.matchHeight-min.js"></script>
<script src="/js/codetabs.js"></script>
<script src="/js/stickysidebar.js"></script>
<!-- Google Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-52545728-1', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>