| <!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> |
| |
| |
| |
| <!-- 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.0/getting-started/project-setup.html" target="_blank">With Flink Stateful Functions <small><span class="glyphicon glyphicon-new-window"></span></small></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.0" target="_blank">Flink Stateful Functions 2.0 (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> |
| |
| |
| <!-- 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> |