| |
| <!DOCTYPE html> |
| <html lang="en" dir=ZgotmplZ> |
| |
| <head> |
| |
| |
| |
| <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css"> |
| <script src="/bootstrap/js/bootstrap.bundle.min.js"></script> |
| <link rel="stylesheet" type="text/css" href="/font-awesome/css/font-awesome.min.css"> |
| <script src="/js/anchor.min.js"></script> |
| <script src="/js/flink.js"></script> |
| <link rel="canonical" href="https://flink.apache.org/how-to-contribute/documentation-style-guide/"> |
| |
| <meta charset="UTF-8"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="description" content="Documentation Style Guide # This guide provides an overview of the essential style guidelines for writing and contributing to the Flink documentation. It’s meant to support your contribution journey in the greater community effort to improve and extend existing documentation — and help make it more accessible, consistent and inclusive. |
| Language # The Flink documentation is maintained in US English and Chinese — when extending or updating the documentation, both versions should be addressed in one pull request."> |
| <meta name="theme-color" content="#FFFFFF"><meta property="og:title" content="Documentation Style Guide" /> |
| <meta property="og:description" content="Documentation Style Guide # This guide provides an overview of the essential style guidelines for writing and contributing to the Flink documentation. It’s meant to support your contribution journey in the greater community effort to improve and extend existing documentation — and help make it more accessible, consistent and inclusive. |
| Language # The Flink documentation is maintained in US English and Chinese — when extending or updating the documentation, both versions should be addressed in one pull request." /> |
| <meta property="og:type" content="article" /> |
| <meta property="og:url" content="https://flink.apache.org/how-to-contribute/documentation-style-guide/" /><meta property="article:section" content="how-to-contribute" /> |
| |
| |
| <title>Documentation Style Guide | Apache Flink</title> |
| <link rel="manifest" href="/manifest.json"> |
| <link rel="icon" href="/favicon.png" type="image/x-icon"> |
| <link rel="alternate" hreflang="zh" href="https://flink.apache.org/zh/how-to-contribute/documentation-style-guide/" title="文档样式指南"> |
| |
| <link rel="stylesheet" href="/book.min.22eceb4d17baa9cdc0f57345edd6f215a40474022dfee39b63befb5fb3c596b5.css" integrity="sha256-IuzrTRe6qc3A9XNF7dbyFaQEdAIt/uObY777X7PFlrU="> |
| <script defer src="/en.search.min.2698f0d1b683dae4d6cb071668b310a55ebcf1c48d11410a015a51d90105b53e.js" integrity="sha256-Jpjw0baD2uTWywcWaLMQpV688cSNEUEKAVpR2QEFtT4="></script> |
| <!-- |
| Made with Book Theme |
| https://github.com/alex-shpak/hugo-book |
| --> |
| |
| <meta name="generator" content="Hugo 0.124.1"> |
| |
| |
| <script> |
| var _paq = window._paq = window._paq || []; |
| |
| |
| _paq.push(['disableCookies']); |
| |
| _paq.push(["setDomains", ["*.flink.apache.org","*.nightlies.apache.org/flink"]]); |
| _paq.push(['trackPageView']); |
| _paq.push(['enableLinkTracking']); |
| (function() { |
| var u="//analytics.apache.org/"; |
| _paq.push(['setTrackerUrl', u+'matomo.php']); |
| _paq.push(['setSiteId', '1']); |
| var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; |
| g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s); |
| })(); |
| </script> |
| |
| </head> |
| |
| <body dir=ZgotmplZ> |
| |
| |
| |
| <header> |
| <nav class="navbar navbar-expand-xl"> |
| <div class="container-fluid"> |
| <a class="navbar-brand" href="/"> |
| <img src="/img/logo/png/100/flink_squirrel_100_color.png" alt="Apache Flink" height="47" width="47" class="d-inline-block align-text-middle"> |
| <span>Apache Flink</span> |
| </a> |
| <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation"> |
| <i class="fa fa-bars navbar-toggler-icon"></i> |
| </button> |
| <div class="collapse navbar-collapse" id="navbarSupportedContent"> |
| <ul class="navbar-nav"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false">About</a> |
| <ul class="dropdown-menu"> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="/what-is-flink/flink-architecture/">Architecture</a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="/what-is-flink/flink-applications/">Applications</a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="/what-is-flink/flink-operations/">Operations</a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="/what-is-flink/use-cases/">Use Cases</a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="/what-is-flink/powered-by/">Powered By</a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="/what-is-flink/roadmap/">Roadmap</a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="/what-is-flink/community/">Community & Project Info</a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="/what-is-flink/security/">Security</a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="/what-is-flink/special-thanks/">Special Thanks</a> |
| |
| |
| </li> |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false">Getting Started</a> |
| <ul class="dropdown-menu"> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-docs-stable/docs/try-flink/local_installation/">With Flink<i class="link fa fa-external-link title" aria-hidden="true"></i> |
| </a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-kubernetes-operator-docs-stable/docs/try-flink-kubernetes-operator/quick-start/">With Flink Kubernetes Operator<i class="link fa fa-external-link title" aria-hidden="true"></i> |
| </a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-cdc-docs-stable/docs/get-started/introduction/">With Flink CDC<i class="link fa fa-external-link title" aria-hidden="true"></i> |
| </a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-ml-docs-stable/docs/try-flink-ml/quick-start/">With Flink ML<i class="link fa fa-external-link title" aria-hidden="true"></i> |
| </a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-statefun-docs-stable/getting-started/project-setup.html">With Flink Stateful Functions<i class="link fa fa-external-link title" aria-hidden="true"></i> |
| </a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-docs-stable/docs/learn-flink/overview/">Training Course<i class="link fa fa-external-link title" aria-hidden="true"></i> |
| </a> |
| |
| |
| </li> |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false">Documentation</a> |
| <ul class="dropdown-menu"> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-docs-stable/">Flink 1.19 (stable)<i class="link fa fa-external-link title" aria-hidden="true"></i> |
| </a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-docs-master/">Flink Master (snapshot)<i class="link fa fa-external-link title" aria-hidden="true"></i> |
| </a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-kubernetes-operator-docs-stable/">Kubernetes Operator 1.8 (latest)<i class="link fa fa-external-link title" aria-hidden="true"></i> |
| </a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-kubernetes-operator-docs-main">Kubernetes Operator Main (snapshot)<i class="link fa fa-external-link title" aria-hidden="true"></i> |
| </a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-cdc-docs-stable">CDC 3.0 (stable)<i class="link fa fa-external-link title" aria-hidden="true"></i> |
| </a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-cdc-docs-master">CDC Master (snapshot)<i class="link fa fa-external-link title" aria-hidden="true"></i> |
| </a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-ml-docs-stable/">ML 2.3 (stable)<i class="link fa fa-external-link title" aria-hidden="true"></i> |
| </a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-ml-docs-master">ML Master (snapshot)<i class="link fa fa-external-link title" aria-hidden="true"></i> |
| </a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-statefun-docs-stable/">Stateful Functions 3.3 (stable)<i class="link fa fa-external-link title" aria-hidden="true"></i> |
| </a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="https://nightlies.apache.org/flink/flink-statefun-docs-master">Stateful Functions Master (snapshot)<i class="link fa fa-external-link title" aria-hidden="true"></i> |
| </a> |
| |
| |
| </li> |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false">How to Contribute</a> |
| <ul class="dropdown-menu"> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="/how-to-contribute/overview/">Overview</a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="/how-to-contribute/contribute-code/">Contribute Code</a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="/how-to-contribute/reviewing-prs/">Review Pull Requests</a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="/how-to-contribute/code-style-and-quality-preamble/">Code Style and Quality Guide</a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="/how-to-contribute/contribute-documentation/">Contribute Documentation</a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="/how-to-contribute/documentation-style-guide/">Documentation Style Guide</a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="/how-to-contribute/improve-website/">Contribute to the Website</a> |
| |
| |
| </li> |
| |
| <li> |
| |
| |
| <a class="dropdown-item" href="/how-to-contribute/getting-help/">Getting Help</a> |
| |
| |
| </li> |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="nav-item"> |
| |
| |
| <a class="nav-link" href="/posts/">Flink Blog</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| <li class="nav-item"> |
| |
| |
| <a class="nav-link" href="/downloads/">Downloads</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| <div class="book-search"> |
| <div class="book-search-spinner hidden"> |
| <i class="fa fa-refresh fa-spin"></i> |
| </div> |
| <form class="search-bar d-flex" onsubmit="return false;"su> |
| <input type="text" id="book-search-input" placeholder="Search" aria-label="Search" maxlength="64" data-hotkeys="s/"> |
| <i class="fa fa-search search"></i> |
| <i class="fa fa-circle-o-notch fa-spin spinner"></i> |
| </form> |
| <div class="book-search-spinner hidden"></div> |
| <ul id="book-search-results"></ul> |
| </div> |
| </div> |
| </div> |
| </nav> |
| <div class="navbar-clearfix"></div> |
| </header> |
| |
| |
| <main class="flex"> |
| <section class="container book-page"> |
| |
| <article class="markdown"><h1 id="documentation-style-guide"> |
| Documentation Style Guide |
| <a class="anchor" href="#documentation-style-guide">#</a> |
| </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> |
| <h2 id="language"> |
| Language |
| <a class="anchor" href="#language">#</a> |
| </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="/what-is-flink/community/#issue-tracker">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> |
| <h2 id="language-style"> |
| Language Style |
| <a class="anchor" href="#language-style">#</a> |
| </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 |
| <a class="anchor" href="#voice-and-tone">#</a> |
| </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> |
| <ul> |
| <li><strong>Active Voice</strong> |
| “You can run this example in your IDE or on the command line.”</li> |
| <li><strong>Passive Voice</strong> |
| “This example can be run in your IDE or on the command line (by zombies).”</li> |
| </ul> |
| </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> |
| <li> |
| <p><strong>Avoid using uppercase words</strong> to highlight or emphasize statements. |
| Highlighting key words with e.g. <strong>bold</strong> or <em>italic</em> font usually appears more polite. |
| If you want to draw attention to important but not obvious statements, |
| try to group them into separate paragraphs starting with a label, |
| highlighted with a corresponding HTML tag:</p> |
| <ul> |
| <li><code><span class="label label-info">Note</span></code></li> |
| <li><code><span class="label label-warning">Warning</span></code></li> |
| <li><code><span class="label label-danger">Danger</span></code></li> |
| </ul> |
| </li> |
| </ul> |
| <h3 id="using-flink-specific-terms"> |
| Using Flink-specific Terms |
| <a class="anchor" href="#using-flink-specific-terms">#</a> |
| </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="//nightlies.apache.org/flink/flink-docs-stable/docs/concepts/glossary"> |
| Flink Glossary. |
| </a> |
| |
| The Glossary is a work in progress, so you can also propose new terms by |
| opening a pull-request.</p> |
| <h2 id="repository"> |
| Repository |
| <a class="anchor" href="#repository">#</a> |
| </h2> |
| <p>Markdown files (.md) should have a short name that summarizes the topic |
| covered, spelled in <strong>lowercase</strong> and with <strong>dashes (-)</strong> separating the |
| words. The Chinese version file should have the same name as the English |
| version, but stored in the <strong>content.zh</strong> folder.</p> |
| <h2 id="syntax"> |
| Syntax |
| <a class="anchor" href="#syntax">#</a> |
| </h2> |
| <p>The documentation website is generated using |
| <a href="https://gohugo.io/">Hugo</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 |
| <a class="anchor" href="#extended-syntax">#</a> |
| </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 |
| <a class="anchor" href="#front-matter">#</a> |
| </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> |
| <h3 id="apache-license"> |
| Apache License |
| <a class="anchor" href="#apache-license">#</a> |
| </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 inthe following example.</p> |
| <pre tabindex="0"><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><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> |
| <pre tabindex="0"><code class="language-liquid" data-lang="liquid">{{ "{{ site.CONFIG_KEY " }}}} |
| </code></pre><p>The placeholder will be replaced with the value of the variable named <code>CONFIG_KEY</code> when generating the documentation.</p> |
| <h2 id="formatting"> |
| Formatting |
| <a class="anchor" href="#formatting">#</a> |
| </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 |
| <a class="anchor" href="#headings">#</a> |
| </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> |
| <h4 id="best-practice"> |
| Best Practice |
| <a class="anchor" href="#best-practice">#</a> |
| </h4> |
| <p>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”.</p> |
| <h3 id="table-of-contents"> |
| Table of Contents |
| <a class="anchor" href="#table-of-contents">#</a> |
| </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> |
| <pre tabindex="0"><code class="language-liquid" data-lang="liquid">{{ "{:toc" }}} |
| </code></pre><p>All headings up to <strong>Level-3</strong> are considered. To exclude a particular heading |
| from the TOC:</p> |
| <pre tabindex="0"><code class="language-liquid" data-lang="liquid">{{ "# Excluded Heading |
| {:.no_toc" }}} |
| </code></pre><h4 id="best-practice-1"> |
| Best Practice |
| <a class="anchor" href="#best-practice-1">#</a> |
| </h4> |
| <p>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.</p> |
| <h3 id="navigation"> |
| Navigation |
| <a class="anchor" href="#navigation">#</a> |
| </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> |
| <pre tabindex="0"><code class="language-liquid" data-lang="liquid">{{ "{% top " }}%} |
| </code></pre><h4 id="best-practice-2"> |
| Best Practice |
| <a class="anchor" href="#best-practice-2">#</a> |
| </h4> |
| <p>It’s recommended to use Back to Top links at least at the end of each Level-2 |
| section.</p> |
| <h3 id="annotations"> |
| Annotations |
| <a class="anchor" href="#annotations">#</a> |
| </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 tabindex="0" class="chroma"><code class="language-html" data-lang="html"><span class="line"><span class="cl"><span class="p"><</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">"alert alert-info"</span><span class="p">></span> // Info Message <span class="p"></</span><span class="nt">div</span><span class="p">></span> |
| </span></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 tabindex="0" class="chroma"><code class="language-html" data-lang="html"><span class="line"><span class="cl"><span class="p"><</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">"alert alert-danger"</span><span class="p">></span> // Danger Message <span class="p"></</span><span class="nt">div</span><span class="p">></span> |
| </span></span></code></pre></div></li> |
| </ul> |
| <h3 id="links"> |
| Links |
| <a class="anchor" href="#links">#</a> |
| </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> |
| <pre tabindex="0"><code class="language-liquid" data-lang="liquid">[Link Text](#heading-title) |
| </code></pre></li> |
| <li> |
| <p><strong>Links to other pages of the Flink documentation.</strong></p> |
| <pre tabindex="0"><code class="language-liquid" data-lang="liquid">[Link Text]({% link path/to/link-page.md %}) |
| </code></pre></li> |
| <li> |
| <p><strong>Links to external pages</strong></p> |
| <pre tabindex="0"><code class="language-liquid" data-lang="liquid">[Link Text](external_url) |
| </code></pre></li> |
| </ul> |
| <h4 id="best-practice-3"> |
| Best Practice |
| <a class="anchor" href="#best-practice-3">#</a> |
| </h4> |
| <p>Use descriptive links that provide information on the action or destination. |
| For example, avoid using “Learn More” or “Click Here” links.</p> |
| <h3 id="visual-elements"> |
| Visual Elements |
| <a class="anchor" href="#visual-elements">#</a> |
| </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> |
| <pre tabindex="0"><code class="language-liquid" data-lang="liquid"> |
| <img |
| src="https://flink.apache.org//fig/image_name.png" |
| alt="Picture Text" |
| width="200px" |
| style="display:block;margin-left:auto;margin-right:auto" |
| > |
| </code></pre><h4 id="best-practice-4"> |
| Best Practice |
| <a class="anchor" href="#best-practice-4">#</a> |
| </h4> |
| <p>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.</p> |
| <h3 id="code"> |
| Code |
| <a class="anchor" href="#code">#</a> |
| </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> |
| <pre tabindex="0"><code class="language-liquid" data-lang="liquid">```java |
| // Java Code |
| ``` |
| </code></pre></li> |
| </ul> |
| <p>When specifying multiple programming languages, each code block should be styled as a tab:</p> |
| <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-html" data-lang="html"><span class="line"><span class="cl"><span class="p"><</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">"codetabs"</span> <span class="na">markdown</span><span class="o">=</span><span class="s">"1"</span><span class="p">></span> |
| </span></span><span class="line"><span class="cl"> |
| </span></span><span class="line"><span class="cl"> <span class="p"><</span><span class="nt">div</span> <span class="na">data-lang</span><span class="o">=</span><span class="s">"java"</span> <span class="na">markdown</span><span class="o">=</span><span class="s">"1"</span><span class="p">></span> |
| </span></span><span class="line"><span class="cl"> |
| </span></span><span class="line"><span class="cl"> ```java |
| </span></span><span class="line"><span class="cl"> // Java Code |
| </span></span><span class="line"><span class="cl"> ``` |
| </span></span><span class="line"><span class="cl"> |
| </span></span><span class="line"><span class="cl"> <span class="p"></</span><span class="nt">div</span><span class="p">></span> |
| </span></span><span class="line"><span class="cl"> |
| </span></span><span class="line"><span class="cl"> <span class="p"><</span><span class="nt">div</span> <span class="na">data-lang</span><span class="o">=</span><span class="s">"scala"</span> <span class="na">markdown</span><span class="o">=</span><span class="s">"1"</span><span class="p">></span> |
| </span></span><span class="line"><span class="cl"> |
| </span></span><span class="line"><span class="cl"> ```scala |
| </span></span><span class="line"><span class="cl"> // Scala Code |
| </span></span><span class="line"><span class="cl"> ``` |
| </span></span><span class="line"><span class="cl"> |
| </span></span><span class="line"><span class="cl"> <span class="p"></</span><span class="nt">div</span><span class="p">></span> |
| </span></span><span class="line"><span class="cl"> |
| </span></span><span class="line"><span class="cl"><span class="p"></</span><span class="nt">div</span><span class="p">></span> |
| </span></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> |
| <li> |
| <p><strong>Commands in code blocks.</strong> Commands can be documented using <code>bash</code> syntax |
| highlighted code blocks. The following items should be considered when adding |
| commands to the documentation:</p> |
| <ul> |
| <li><strong>Use long parameter names.</strong> Long parameter names help the reader to |
| understand the purpose of the command. They should be preferred over their |
| short counterparts.</li> |
| <li><strong>One parameter per line.</strong> Using long parameter names makes the command |
| possibly harder to read. Putting one parameter per line improves the |
| readability. You need to add a backslash <code>\</code> escaping the newline at |
| the end of each intermediate line to support copy&paste.</li> |
| <li><strong>Indentation</strong>. Each new parameter line should be indented by 6 spaces.</li> |
| <li><strong>Use <code>$</code> prefix to indicate command start</strong>. The readability of the code |
| block might worsen having multiple commands in place. Putting a dollar sign |
| <code>$</code> in front of each new commands helps identifying the start of a |
| command.</li> |
| </ul> |
| <p>A properly formatted command would look like this:</p> |
| </li> |
| </ul> |
| <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">$ ./bin/flink run-application <span class="se">\ |
| </span></span></span><span class="line"><span class="cl"><span class="se"></span>--target kubernetes-application <span class="se">\ |
| </span></span></span><span class="line"><span class="cl"><span class="se"></span>-Dkubernetes.cluster-id<span class="o">=</span>my-first-application-cluster <span class="se">\ |
| </span></span></span><span class="line"><span class="cl"><span class="se"></span>-Dkubernetes.container.image<span class="o">=</span>custom-image-name <span class="se">\ |
| </span></span></span><span class="line"><span class="cl"><span class="se"></span>local:///opt/flink/usrlib/my-flink-job.jar |
| </span></span></code></pre></div><h2 id="general-guiding-principles"> |
| General Guiding Principles |
| <a class="anchor" href="#general-guiding-principles">#</a> |
| </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 |
| <a class="anchor" href="#accessible">#</a> |
| </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 |
| <a class="anchor" href="#consistent">#</a> |
| </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 |
| <a class="anchor" href="#objective">#</a> |
| </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 |
| <a class="anchor" href="#logical">#</a> |
| </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 |
| <a class="anchor" href="#inclusive">#</a> |
| </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> |
| </article> |
| |
| |
| |
| |
| |
| |
| |
| <div class="edit-this-page"> |
| <p> |
| <a href="https://cwiki.apache.org/confluence/display/FLINK/Flink+Translation+Specifications">Want to contribute translation?</a> |
| </p> |
| <p> |
| <a href="//github.com/apache/flink-web/edit/asf-site/docs/content/how-to-contribute/documentation-style-guide.md"> |
| Edit This Page<i class="fa fa-edit fa-fw"></i> |
| </a> |
| </p> |
| </div> |
| |
| </section> |
| |
| <aside class="book-toc"> |
| |
| |
| |
| <nav id="TableOfContents"><h3>On This Page <a href="javascript:void(0)" class="toc" onclick="collapseToc()"><i class="fa fa-times" aria-hidden="true"></i></a></h3> |
| <ul> |
| <li><a href="#documentation-style-guide">Documentation Style Guide</a> |
| <ul> |
| <li><a href="#language">Language</a></li> |
| <li><a href="#language-style">Language Style</a> |
| <ul> |
| <li><a href="#voice-and-tone">Voice and Tone</a></li> |
| <li><a href="#using-flink-specific-terms">Using Flink-specific Terms</a></li> |
| </ul> |
| </li> |
| <li><a href="#repository">Repository</a></li> |
| <li><a href="#syntax">Syntax</a> |
| <ul> |
| <li><a href="#extended-syntax">Extended Syntax</a></li> |
| <li><a href="#front-matter">Front Matter</a></li> |
| <li><a href="#apache-license">Apache License</a></li> |
| </ul> |
| </li> |
| <li><a href="#formatting">Formatting</a> |
| <ul> |
| <li><a href="#headings">Headings</a></li> |
| <li><a href="#table-of-contents">Table of Contents</a></li> |
| <li><a href="#navigation">Navigation</a></li> |
| <li><a href="#annotations">Annotations</a></li> |
| <li><a href="#links">Links</a></li> |
| <li><a href="#visual-elements">Visual Elements</a></li> |
| <li><a href="#code">Code</a></li> |
| </ul> |
| </li> |
| <li><a href="#general-guiding-principles">General Guiding Principles</a> |
| <ul> |
| <li></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </nav> |
| |
| |
| </aside> |
| <aside class="expand-toc hidden"> |
| <a class="toc" onclick="expandToc()" href="javascript:void(0)"> |
| <i class="fa fa-bars" aria-hidden="true"></i> |
| </a> |
| </aside> |
| |
| </main> |
| |
| <footer> |
| |
| |
| |
| <div class="separator"></div> |
| <div class="panels"> |
| <div class="wrapper"> |
| <div class="panel"> |
| <ul> |
| <li> |
| <a href="https://flink-packages.org/">flink-packages.org</a> |
| </li> |
| <li> |
| <a href="https://www.apache.org/">Apache Software Foundation</a> |
| </li> |
| <li> |
| <a href="https://www.apache.org/licenses/">License</a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li> |
| <a href="/zh/how-to-contribute/documentation-style-guide/"> |
| <i class="fa fa-globe" aria-hidden="true"></i> 中文版 |
| </a> |
| </li> |
| |
| |
| |
| </ul> |
| </div> |
| <div class="panel"> |
| <ul> |
| <li> |
| <a href="/what-is-flink/security">Security</a--> |
| </li> |
| <li> |
| <a href="https://www.apache.org/foundation/sponsorship.html">Donate</a> |
| </li> |
| <li> |
| <a href="https://www.apache.org/foundation/thanks.html">Thanks</a> |
| </li> |
| </ul> |
| </div> |
| <div class="panel icons"> |
| <div> |
| <a href="/posts"> |
| <div class="icon flink-blog-icon"></div> |
| <span>Flink blog</span> |
| </a> |
| </div> |
| <div> |
| <a href="https://github.com/apache/flink"> |
| <div class="icon flink-github-icon"></div> |
| <span>Github</span> |
| </a> |
| </div> |
| <div> |
| <a href="https://twitter.com/apacheflink"> |
| <div class="icon flink-twitter-icon"></div> |
| <span>Twitter</span> |
| </a> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| <hr/> |
| |
| <div class="container disclaimer"> |
| <p>The contents of this website are © 2024 Apache Software Foundation under the terms of the Apache License v2. Apache Flink, Flink, and the Flink logo are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries.</p> |
| </div> |
| |
| |
| |
| </footer> |
| |
| </body> |
| </html> |
| |
| |
| |
| |
| |
| |
