This is an automated email from the ASF dual-hosted git repository.
aljoscha pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/flink-web.git
commit 3a91cffe47fe46179c78a1b7bef47adf4f8b7d81
Author: Aljoscha Krettek <aljoscha.kret...@gmail.com>
AuthorDate: Fri Feb 14 16:09:13 2020 +0100
Rebuild website
---
.../code-style-and-quality-common.html | 3 +
.../code-style-and-quality-components.html | 3 +
.../code-style-and-quality-formatting.html | 3 +
.../contributing/code-style-and-quality-java.html | 3 +
.../code-style-and-quality-preamble.html | 3 +
.../code-style-and-quality-pull-requests.html | 3 +
.../contributing/code-style-and-quality-scala.html | 3 +
content/contributing/contribute-code.html | 3 +
content/contributing/contribute-documentation.html | 5 +
content/contributing/docs-style.html | 774 +++++++++++++++++++++
content/contributing/how-to-contribute.html | 3 +
content/contributing/improve-website.html | 3 +
content/contributing/reviewing-prs.html | 3 +
.../code-style-and-quality-common.html | 3 +
.../code-style-and-quality-components.html | 3 +
.../code-style-and-quality-formatting.html | 3 +
.../contributing/code-style-and-quality-java.html | 3 +
.../code-style-and-quality-preamble.html | 3 +
.../code-style-and-quality-pull-requests.html | 3 +
.../contributing/code-style-and-quality-scala.html | 3 +
content/zh/contributing/contribute-code.html | 3 +
.../zh/contributing/contribute-documentation.html | 3 +
content/zh/contributing/docs-style.html | 772 ++++++++++++++++++++
content/zh/contributing/how-to-contribute.html | 3 +
content/zh/contributing/improve-website.html | 3 +
content/zh/contributing/reviewing-prs.html | 3 +
26 files changed, 1620 insertions(+)
diff --git a/content/contributing/code-style-and-quality-common.html
b/content/contributing/code-style-and-quality-common.html
index 256ef07..d111872 100644
--- a/content/contributing/code-style-and-quality-common.html
+++ b/content/contributing/code-style-and-quality-common.html
@@ -138,6 +138,9 @@
<a
href="/contributing/contribute-documentation.html">Contribute Documentation</a>
</li>
<li >
+ <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>
diff --git a/content/contributing/code-style-and-quality-components.html
b/content/contributing/code-style-and-quality-components.html
index aa2572d..e4c70cb 100644
--- a/content/contributing/code-style-and-quality-components.html
+++ b/content/contributing/code-style-and-quality-components.html
@@ -138,6 +138,9 @@
<a
href="/contributing/contribute-documentation.html">Contribute Documentation</a>
</li>
<li >
+ <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>
diff --git a/content/contributing/code-style-and-quality-formatting.html
b/content/contributing/code-style-and-quality-formatting.html
index bd5b38f..8d7ec8c 100644
--- a/content/contributing/code-style-and-quality-formatting.html
+++ b/content/contributing/code-style-and-quality-formatting.html
@@ -138,6 +138,9 @@
<a
href="/contributing/contribute-documentation.html">Contribute Documentation</a>
</li>
<li >
+ <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>
diff --git a/content/contributing/code-style-and-quality-java.html
b/content/contributing/code-style-and-quality-java.html
index d51202e..5bcdea9 100644
--- a/content/contributing/code-style-and-quality-java.html
+++ b/content/contributing/code-style-and-quality-java.html
@@ -138,6 +138,9 @@
<a
href="/contributing/contribute-documentation.html">Contribute Documentation</a>
</li>
<li >
+ <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>
diff --git a/content/contributing/code-style-and-quality-preamble.html
b/content/contributing/code-style-and-quality-preamble.html
index 02076ce..97865fd 100644
--- a/content/contributing/code-style-and-quality-preamble.html
+++ b/content/contributing/code-style-and-quality-preamble.html
@@ -138,6 +138,9 @@
<a
href="/contributing/contribute-documentation.html">Contribute Documentation</a>
</li>
<li >
+ <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>
diff --git a/content/contributing/code-style-and-quality-pull-requests.html
b/content/contributing/code-style-and-quality-pull-requests.html
index cf2d1d1..1e3766d 100644
--- a/content/contributing/code-style-and-quality-pull-requests.html
+++ b/content/contributing/code-style-and-quality-pull-requests.html
@@ -138,6 +138,9 @@
<a
href="/contributing/contribute-documentation.html">Contribute Documentation</a>
</li>
<li >
+ <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>
diff --git a/content/contributing/code-style-and-quality-scala.html
b/content/contributing/code-style-and-quality-scala.html
index 4c6865a..3c74ed7 100644
--- a/content/contributing/code-style-and-quality-scala.html
+++ b/content/contributing/code-style-and-quality-scala.html
@@ -138,6 +138,9 @@
<a
href="/contributing/contribute-documentation.html">Contribute Documentation</a>
</li>
<li >
+ <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>
diff --git a/content/contributing/contribute-code.html
b/content/contributing/contribute-code.html
index 18fec41..f58f260 100644
--- a/content/contributing/contribute-code.html
+++ b/content/contributing/contribute-code.html
@@ -138,6 +138,9 @@
<a
href="/contributing/contribute-documentation.html">Contribute Documentation</a>
</li>
<li >
+ <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>
diff --git a/content/contributing/contribute-documentation.html
b/content/contributing/contribute-documentation.html
index 7c71969..825295f 100644
--- a/content/contributing/contribute-documentation.html
+++ b/content/contributing/contribute-documentation.html
@@ -138,6 +138,9 @@
<a
href="/contributing/contribute-documentation.html">Contribute Documentation</a>
</li>
<li >
+ <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>
@@ -230,6 +233,8 @@
<p>… please make sure there exists a <a
href="https://issues.apache.org/jira/browse/FLINK";>Jira</a> issue that
corresponds to your contribution. We require all documentation changes to refer
to a Jira issue, except for trivial fixes such as typos.</p>
+<p>Also, have a look at the <a
href="/contributing/docs-style.html">Documentation Style Guide</a> for some
guidance on how to write accessible, consistent and inclusive documentation.</p>
+
<h2 id="update-or-extend-the-documentation">Update or extend the
documentation</h2>
<p>The Flink documentation is written in <a
href="http://daringfireball.net/projects/markdown/";>Markdown</a>. Markdown is a
lightweight markup language which can be translated to HTML.</p>
diff --git a/content/contributing/docs-style.html
b/content/contributing/docs-style.html
new file mode 100644
index 0000000..b4ed0a2
--- /dev/null
+++ b/content/contributing/docs-style.html
@@ -0,0 +1,774 @@
+<!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>
+
+
+
+ <!-- Use cases -->
+ <li><a href="/usecases.html">Use Cases</a></li>
+
+ <!-- Powered by -->
+ <li><a href="/poweredby.html">Powered By</a></li>
+
+ <!-- FAQ -->
+ <li><a href="/faq.html">FAQ</a></li>
+
+
+ <!-- Second menu section aims to support Flink users -->
+
+ <!-- Downloads -->
+ <li><a href="/downloads.html">Downloads</a></li>
+
+ <!-- Getting Started -->
+ <li>
+ <a
href="https://ci.apache.org/projects/flink/flink-docs-release-1.10/getting-started/index.html";
target="_blank">Getting Started <small><span class="glyphicon
glyphicon-new-window"></span></small></a>
+ </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">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">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>
+
+
+ <!-- Third menu section aim to support community and contributors
-->
+
+ <!-- Community -->
+ <li><a href="/community.html">Community & 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>
+
+
+
+ <!-- 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
+---
+<!--
+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.
+-->
+</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"><div</span> <span class="na">class=</span><span
class="s">"alert alert-info"</span><span class="nt">></span> //
Info Message <span class="nt"></div></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"><div</span> <span class="na">class=</span><span
class="s">"alert alert-danger"</span><span class="nt">></span> //
Danger Message <span class="nt"></div></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> The
base relative path
+to the domain of the documentation is available as a configuration variable
+named <code>baseurl</code>.</p>
+
+ <div class="highlight"><pre><code class="language-liquid">[Link
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><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="200px"
width="200px"}</code></pre></div>
+
+<p>Or using plain HTML:</p>
+
+<figure class="highlight"><pre><code class="language-html"
data-lang="html"><span class="nt"><img</span> <span
class="na">src=</span><span class="s">"/fig/image_name.png"</span>
<span class="na">class=</span><span class="s">"center"</span> <span
class="na">height=</span><span class="s">"200px"</span> <span
class="na">width=</span><span class="s">"200px"</span><span
class="nt">/></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"><div</span> <span class="na">class=</span><span
class="s">"codetabs"</span> <span class="na">markdown=</span><span
class="s">"1"</span><span class="nt">></span>
+
+ <span class="nt"><div</span> <span class="na">data-lang=</span><span
class="s">"java"</span> <span class="na">markdown=</span><span
class="s">"1"</span><span class="nt">></span>
+
+ {% highlight java%}
+ // Java Code
+ {% endhighlight%}
+
+ <span class="nt"></div></span>
+
+ <span class="nt"><div</span> <span class="na">data-lang=</span><span
class="s">"scala"</span> <span class="na">markdown=</span><span
class="s">"1"</span><span class="nt">></span>
+
+ {% highlight scala%}
+ // Scala Code
+ {% endhighlight%}
+
+ <span class="nt"></div></span>
+
+<span class="nt"></div></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> · <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>
diff --git a/content/contributing/how-to-contribute.html
b/content/contributing/how-to-contribute.html
index 4c95222..ee518a7 100644
--- a/content/contributing/how-to-contribute.html
+++ b/content/contributing/how-to-contribute.html
@@ -138,6 +138,9 @@
<a
href="/contributing/contribute-documentation.html">Contribute Documentation</a>
</li>
<li >
+ <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>
diff --git a/content/contributing/improve-website.html
b/content/contributing/improve-website.html
index ce36612..a711a72 100644
--- a/content/contributing/improve-website.html
+++ b/content/contributing/improve-website.html
@@ -137,6 +137,9 @@
<li >
<a
href="/contributing/contribute-documentation.html">Contribute Documentation</a>
</li>
+ <li >
+ <a href="/contributing/docs-style.html">Documentation Style
Guide</a>
+ </li>
<li class="active">
<a href="/contributing/improve-website.html">Contribute to
the Website</a>
</li>
diff --git a/content/contributing/reviewing-prs.html
b/content/contributing/reviewing-prs.html
index 50ce061..15d21f7 100644
--- a/content/contributing/reviewing-prs.html
+++ b/content/contributing/reviewing-prs.html
@@ -138,6 +138,9 @@
<a
href="/contributing/contribute-documentation.html">Contribute Documentation</a>
</li>
<li >
+ <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>
diff --git a/content/zh/contributing/code-style-and-quality-common.html
b/content/zh/contributing/code-style-and-quality-common.html
index 845c47d..15a2994 100644
--- a/content/zh/contributing/code-style-and-quality-common.html
+++ b/content/zh/contributing/code-style-and-quality-common.html
@@ -138,6 +138,9 @@
<a
href="/zh/contributing/contribute-documentation.html">贡献文档</a>
</li>
<li >
+ <a href="/zh/contributing/docs-style.html">Documentation
Style Guide</a>
+ </li>
+ <li >
<a href="/zh/contributing/improve-website.html">贡献网站</a>
</li>
</ul>
diff --git a/content/zh/contributing/code-style-and-quality-components.html
b/content/zh/contributing/code-style-and-quality-components.html
index e8f47e3..81cd688 100644
--- a/content/zh/contributing/code-style-and-quality-components.html
+++ b/content/zh/contributing/code-style-and-quality-components.html
@@ -138,6 +138,9 @@
<a
href="/zh/contributing/contribute-documentation.html">贡献文档</a>
</li>
<li >
+ <a href="/zh/contributing/docs-style.html">Documentation
Style Guide</a>
+ </li>
+ <li >
<a href="/zh/contributing/improve-website.html">贡献网站</a>
</li>
</ul>
diff --git a/content/zh/contributing/code-style-and-quality-formatting.html
b/content/zh/contributing/code-style-and-quality-formatting.html
index a5eb9b7..6688805 100644
--- a/content/zh/contributing/code-style-and-quality-formatting.html
+++ b/content/zh/contributing/code-style-and-quality-formatting.html
@@ -138,6 +138,9 @@
<a
href="/zh/contributing/contribute-documentation.html">贡献文档</a>
</li>
<li >
+ <a href="/zh/contributing/docs-style.html">Documentation
Style Guide</a>
+ </li>
+ <li >
<a href="/zh/contributing/improve-website.html">贡献网站</a>
</li>
</ul>
diff --git a/content/zh/contributing/code-style-and-quality-java.html
b/content/zh/contributing/code-style-and-quality-java.html
index 9319212..35d50c8 100644
--- a/content/zh/contributing/code-style-and-quality-java.html
+++ b/content/zh/contributing/code-style-and-quality-java.html
@@ -138,6 +138,9 @@
<a
href="/zh/contributing/contribute-documentation.html">贡献文档</a>
</li>
<li >
+ <a href="/zh/contributing/docs-style.html">Documentation
Style Guide</a>
+ </li>
+ <li >
<a href="/zh/contributing/improve-website.html">贡献网站</a>
</li>
</ul>
diff --git a/content/zh/contributing/code-style-and-quality-preamble.html
b/content/zh/contributing/code-style-and-quality-preamble.html
index ff2add1..c0d70ee 100644
--- a/content/zh/contributing/code-style-and-quality-preamble.html
+++ b/content/zh/contributing/code-style-and-quality-preamble.html
@@ -138,6 +138,9 @@
<a
href="/zh/contributing/contribute-documentation.html">贡献文档</a>
</li>
<li >
+ <a href="/zh/contributing/docs-style.html">Documentation
Style Guide</a>
+ </li>
+ <li >
<a href="/zh/contributing/improve-website.html">贡献网站</a>
</li>
</ul>
diff --git a/content/zh/contributing/code-style-and-quality-pull-requests.html
b/content/zh/contributing/code-style-and-quality-pull-requests.html
index d40d581..d3ecfb2 100644
--- a/content/zh/contributing/code-style-and-quality-pull-requests.html
+++ b/content/zh/contributing/code-style-and-quality-pull-requests.html
@@ -138,6 +138,9 @@
<a
href="/zh/contributing/contribute-documentation.html">贡献文档</a>
</li>
<li >
+ <a href="/zh/contributing/docs-style.html">Documentation
Style Guide</a>
+ </li>
+ <li >
<a href="/zh/contributing/improve-website.html">贡献网站</a>
</li>
</ul>
diff --git a/content/zh/contributing/code-style-and-quality-scala.html
b/content/zh/contributing/code-style-and-quality-scala.html
index 5a1bc4b..62b2115 100644
--- a/content/zh/contributing/code-style-and-quality-scala.html
+++ b/content/zh/contributing/code-style-and-quality-scala.html
@@ -138,6 +138,9 @@
<a
href="/zh/contributing/contribute-documentation.html">贡献文档</a>
</li>
<li >
+ <a href="/zh/contributing/docs-style.html">Documentation
Style Guide</a>
+ </li>
+ <li >
<a href="/zh/contributing/improve-website.html">贡献网站</a>
</li>
</ul>
diff --git a/content/zh/contributing/contribute-code.html
b/content/zh/contributing/contribute-code.html
index 1cdcf43..8a72811 100644
--- a/content/zh/contributing/contribute-code.html
+++ b/content/zh/contributing/contribute-code.html
@@ -138,6 +138,9 @@
<a
href="/zh/contributing/contribute-documentation.html">贡献文档</a>
</li>
<li >
+ <a href="/zh/contributing/docs-style.html">Documentation
Style Guide</a>
+ </li>
+ <li >
<a href="/zh/contributing/improve-website.html">贡献网站</a>
</li>
</ul>
diff --git a/content/zh/contributing/contribute-documentation.html
b/content/zh/contributing/contribute-documentation.html
index b9cd1db..662be50 100644
--- a/content/zh/contributing/contribute-documentation.html
+++ b/content/zh/contributing/contribute-documentation.html
@@ -138,6 +138,9 @@
<a
href="/zh/contributing/contribute-documentation.html">贡献文档</a>
</li>
<li >
+ <a href="/zh/contributing/docs-style.html">Documentation
Style Guide</a>
+ </li>
+ <li >
<a href="/zh/contributing/improve-website.html">贡献网站</a>
</li>
</ul>
diff --git a/content/zh/contributing/docs-style.html
b/content/zh/contributing/docs-style.html
new file mode 100644
index 0000000..2fa6464
--- /dev/null
+++ b/content/zh/contributing/docs-style.html
@@ -0,0 +1,772 @@
+<!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="/zh/">
+ <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="/zh/streamprocessing1.html">What is Stream
Processing?</a></li>
+ -->
+
+ <!-- What is Flink? -->
+ <li><a href="/zh/flink-architecture.html">Apache Flink
是什么?</a></li>
+
+
+
+ <!-- Use cases -->
+ <li><a href="/zh/usecases.html">应用场景</a></li>
+
+ <!-- Powered by -->
+ <li><a href="/zh/poweredby.html">Flink 用户</a></li>
+
+ <!-- FAQ -->
+ <li><a href="/zh/faq.html">常见问题</a></li>
+
+
+ <!-- Second menu section aims to support Flink users -->
+
+ <!-- Downloads -->
+ <li><a href="/zh/downloads.html">下载</a></li>
+
+ <!-- Getting Started -->
+ <li>
+ <a
href="https://ci.apache.org/projects/flink/flink-docs-release-1.10/zh/getting-started/index.html";
target="_blank">教程 <small><span class="glyphicon
glyphicon-new-window"></span></small></a>
+ </li>
+
+ <!-- Documentation -->
+ <li class="dropdown">
+ <a class="dropdown-toggle" data-toggle="dropdown"
href="#">文档<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">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">Master (Latest Snapshot) <small><span class="glyphicon
glyphicon-new-window"></span></small></a></li>
+ </ul>
+ </li>
+
+ <!-- getting help -->
+ <li><a href="/zh/gettinghelp.html">获取帮助</a></li>
+
+ <!-- Blog -->
+ <li><a href="/blog/"><b>Flink 博客</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>
+
+
+ <!-- Third menu section aim to support community and contributors
-->
+
+ <!-- Community -->
+ <li><a href="/zh/community.html">社区 & 项目信息</a></li>
+
+ <!-- Roadmap -->
+ <li><a href="/zh/roadmap.html">开发计划</a></li>
+
+ <!-- Contribute -->
+ <li><a
href="/zh/contributing/how-to-contribute.html">如何参与贡献</a></li>
+
+ <ul class="nav navbar-nav navbar-subnav">
+ <li >
+ <a href="/zh/contributing/contribute-code.html">贡献代码</a>
+ </li>
+ <li >
+ <a href="/zh/contributing/reviewing-prs.html">审核 Pull
Request</a>
+ </li>
+ <li >
+ <a
href="/zh/contributing/code-style-and-quality-preamble.html">代码样式与质量指南</a>
+ </li>
+ <li >
+ <a
href="/zh/contributing/contribute-documentation.html">贡献文档</a>
+ </li>
+ <li class="active">
+ <a href="/zh/contributing/docs-style.html">Documentation
Style Guide</a>
+ </li>
+ <li >
+ <a href="/zh/contributing/improve-website.html">贡献网站</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>
+
+
+
+ <!-- Language Switcher -->
+ <li>
+
+ <a href="/contributing/docs-style.html">English</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
+---
+<!--
+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.
+-->
+</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"><div</span> <span class="na">class=</span><span
class="s">"alert alert-info"</span><span class="nt">></span> //
Info Message <span class="nt"></div></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"><div</span> <span class="na">class=</span><span
class="s">"alert alert-danger"</span><span class="nt">></span> //
Danger Message <span class="nt"></div></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> The
base relative path
+to the domain of the documentation is available as a configuration variable
+named <code>baseurl</code>.</p>
+
+ <div class="highlight"><pre><code class="language-liquid">[Link
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><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="200px"
width="200px"}</code></pre></div>
+
+<p>Or using plain HTML:</p>
+
+<figure class="highlight"><pre><code class="language-html"
data-lang="html"><span class="nt"><img</span> <span
class="na">src=</span><span class="s">"/fig/image_name.png"</span>
<span class="na">class=</span><span class="s">"center"</span> <span
class="na">height=</span><span class="s">"200px"</span> <span
class="na">width=</span><span class="s">"200px"</span><span
class="nt">/></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"><div</span> <span class="na">class=</span><span
class="s">"codetabs"</span> <span class="na">markdown=</span><span
class="s">"1"</span><span class="nt">></span>
+
+ <span class="nt"><div</span> <span class="na">data-lang=</span><span
class="s">"java"</span> <span class="na">markdown=</span><span
class="s">"1"</span><span class="nt">></span>
+
+ {% highlight java%}
+ // Java Code
+ {% endhighlight%}
+
+ <span class="nt"></div></span>
+
+ <span class="nt"><div</span> <span class="na">data-lang=</span><span
class="s">"scala"</span> <span class="na">markdown=</span><span
class="s">"1"</span><span class="nt">></span>
+
+ {% highlight scala%}
+ // Scala Code
+ {% endhighlight%}
+
+ <span class="nt"></div></span>
+
+<span class="nt"></div></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> · <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>
diff --git a/content/zh/contributing/how-to-contribute.html
b/content/zh/contributing/how-to-contribute.html
index 3b4ffd9..728a7fa 100644
--- a/content/zh/contributing/how-to-contribute.html
+++ b/content/zh/contributing/how-to-contribute.html
@@ -138,6 +138,9 @@
<a
href="/zh/contributing/contribute-documentation.html">贡献文档</a>
</li>
<li >
+ <a href="/zh/contributing/docs-style.html">Documentation
Style Guide</a>
+ </li>
+ <li >
<a href="/zh/contributing/improve-website.html">贡献网站</a>
</li>
</ul>
diff --git a/content/zh/contributing/improve-website.html
b/content/zh/contributing/improve-website.html
index 7faba8d..8669798 100644
--- a/content/zh/contributing/improve-website.html
+++ b/content/zh/contributing/improve-website.html
@@ -137,6 +137,9 @@
<li >
<a
href="/zh/contributing/contribute-documentation.html">贡献文档</a>
</li>
+ <li >
+ <a href="/zh/contributing/docs-style.html">Documentation
Style Guide</a>
+ </li>
<li class="active">
<a href="/zh/contributing/improve-website.html">贡献网站</a>
</li>
diff --git a/content/zh/contributing/reviewing-prs.html
b/content/zh/contributing/reviewing-prs.html
index 1a20549..bbdc76f 100644
--- a/content/zh/contributing/reviewing-prs.html
+++ b/content/zh/contributing/reviewing-prs.html
@@ -138,6 +138,9 @@
<a
href="/zh/contributing/contribute-documentation.html">贡献文档</a>
</li>
<li >
+ <a href="/zh/contributing/docs-style.html">Documentation
Style Guide</a>
+ </li>
+ <li >
<a href="/zh/contributing/improve-website.html">贡献网站</a>
</li>
</ul>
