mirror of https://github.com/status-im/specs.git
5 lines
12 KiB
HTML
5 lines
12 KiB
HTML
<!DOCTYPE html> <html lang="en-US"> <head> <meta charset="UTF-8"> <meta http-equiv="X-UA-Compatible" content="IE=Edge"> <title>STYLE-GUIDELINE - Status Specification</title> <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon"> <link rel="stylesheet" href="/assets/css/just-the-docs-default.css"> <script type="text/javascript" src="/assets/js/vendor/lunr.min.js"></script> <script type="text/javascript" src="/assets/js/just-the-docs.js"></script> <meta name="viewport" content="width=device-width, initial-scale=1"> <!-- Begin Jekyll SEO tag v2.7.1 --> <title>STYLE-GUIDELINE | Status Specification</title> <meta name="generator" content="Jekyll v4.2.1" /> <meta property="og:title" content="STYLE-GUIDELINE" /> <meta property="og:locale" content="en_US" /> <link rel="canonical" href="https://specs.status.im/style-guideline" /> <meta property="og:url" content="https://specs.status.im/style-guideline" /> <meta property="og:site_name" content="Status Specification" /> <meta name="twitter:card" content="summary" /> <meta property="twitter:title" content="STYLE-GUIDELINE" /> <script type="application/ld+json"> {"@type":"WebPage","url":"https://specs.status.im/style-guideline","headline":"STYLE-GUIDELINE","@context":"https://schema.org"}</script> <!-- End Jekyll SEO tag --> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-link" viewBox="0 0 24 24"> <title>Link</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"> <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path> </svg> </symbol> <symbol id="svg-search" viewBox="0 0 24 24"> <title>Search</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-search"> <circle cx="11" cy="11" r="8"></circle><line x1="21" y1="21" x2="16.65" y2="16.65"></line> </svg> </symbol> <symbol id="svg-menu" viewBox="0 0 24 24"> <title>Menu</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-menu"> <line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line> </svg> </symbol> <symbol id="svg-arrow-right" viewBox="0 0 24 24"> <title>Expand</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-chevron-right"> <polyline points="9 18 15 12 9 6"></polyline> </svg> </symbol> <symbol id="svg-doc" viewBox="0 0 24 24"> <title>Document</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file"> <path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline> </svg> </symbol> </svg> <div class="side-bar"> <div class="site-header"> <a href="https://specs.status.im/" class="site-title lh-tight"> Status Specification </a> <a href="#" id="menu-button" class="site-button"> <svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-menu"></use></svg> </a> </div> <nav role="navigation" aria-label="Main" id="site-nav" class="site-nav"> <ul class="nav-list"><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="https://specs.status.im/stable/" class="nav-list-link">Stable specs</a><ul class="nav-list "><li class="nav-list-item "><a href="https://specs.status.im/stable/1" class="nav-list-link">1/CLIENT</a></li><li class="nav-list-item "><a href="https://specs.status.im/stable/10" class="nav-list-link">10/WAKU-USAGE</a></li><li class="nav-list-item "><a href="https://specs.status.im/stable/11" class="nav-list-link">11/WAKU-MAILSERVER</a></li><li class="nav-list-item "><a href="https://specs.status.im/stable/15" class="nav-list-link">15/NOTIFICATIONS</a></li><li class="nav-list-item "><a href="https://specs.status.im/stable/2" class="nav-list-link">2/ACCOUNT</a></li><li class="nav-list-item "><a href="https://specs.status.im/stable/3" class="nav-list-link">3/WHISPER-USAGE</a></li><li class="nav-list-item "><a href="https://specs.status.im/stable/4" class="nav-list-link">4/WHISPER-MAILSERVER</a></li><li class="nav-list-item "><a href="https://specs.status.im/stable/5" class="nav-list-link">5/SECURE-TRANSPORT</a></li><li class="nav-list-item "><a href="https://specs.status.im/stable/6" class="nav-list-link">6/PAYLOADS</a></li><li class="nav-list-item "><a href="https://specs.status.im/stable/8" class="nav-list-link">8/EIPS</a></li><li class="nav-list-item "><a href="https://specs.status.im/stable/9" class="nav-list-link">9/ETHEREUM-USAGE</a></li></ul></li><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="https://specs.status.im/draft/" class="nav-list-link">Draft specs</a><ul class="nav-list "><li class="nav-list-item "><a href="https://specs.status.im/draft/12" class="nav-list-link">12/IPFS gateway for Sticker Pack</a></li><li class="nav-list-item "><a href="https://specs.status.im/draft/13" class="nav-list-link">13/3RD-PARTY-USAGE</a></li><li class="nav-list-item "><a href="https://specs.status.im/draft/14" class="nav-list-link">14/Dapp browser API usage</a></li><li class="nav-list-item "><a href="https://specs.status.im/draft/16" class="nav-list-link">16/Keycard Usage for Wallet and Chat Keys</a></li><li class="nav-list-item "><a href="https://specs.status.im/draft/3" class="nav-list-link">3/WHISPER-USAGE</a></li><li class="nav-list-item "><a href="https://specs.status.im/draft/6" class="nav-list-link">6/PAYLOADS</a></li><li class="nav-list-item "><a href="https://specs.status.im/draft/7" class="nav-list-link">7/GROUP-CHAT</a></li></ul></li><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="https://specs.status.im/raw/" class="nav-list-link">Raw specs</a><ul class="nav-list "><li class="nav-list-item "><a href="https://specs.status.im/raw/16" class="nav-list-link">16/PUSH-NOTIFICATION-SERVER</a></li></ul></li><li class="nav-list-item"><a href="https://specs.status.im/development" class="nav-list-link">DEVELOPMENT</a></li><li class="nav-list-item active"><a href="https://specs.status.im/style-guideline" class="nav-list-link active">STYLE-GUIDELINE</a></li></ul> </nav> <footer class="site-footer"> This site uses <a href="https://github.com/pmarsceill/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll. </footer> </div> <div class="main" id="top"> <div id="main-header" class="main-header"> <div class="search"> <div class="search-input-wrap"> <input type="text" id="search-input" class="search-input" tabindex="0" placeholder="Search Status Specification" aria-label="Search Status Specification" autocomplete="off"> <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#svg-search"></use></svg></label> </div> <div id="search-results" class="search-results"></div> </div> </div> <div id="main-content-wrap" class="main-content-wrap"> <div id="main-content" class="main-content" role="main"> <h1 id="style-guidelines-for-status-client-specifications"> <a href="#style-guidelines-for-status-client-specifications" class="anchor-heading" aria-labelledby="style-guidelines-for-status-client-specifications"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Style guidelines for Status client specifications </h1> <ul> <li><a href="#spellcheck">Spellcheck</a></li> <li><a href="#markdown-verification">Markdown Verification</a></li> <li><a href="#language-mode">Language Mode</a></li> </ul> <h2 id="spellcheck"> <a href="#spellcheck" class="anchor-heading" aria-labelledby="spellcheck"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Spellcheck </h2> <p>To run the spellchecker locally, you must install <a href="https://facelessuser.github.io/pyspelling/">pyspelling</a>.</p> <p>It can then be run with the following command:</p> <div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="go">pyspelling -c spellcheck.yml
|
|
</span></code></pre></div></div> <p>Words that should be ignored or are unrecognized must be added to the <a href="./wordlist.txt">wordlist</a>.</p> <h2 id="markdown-verification"> <a href="#markdown-verification" class="anchor-heading" aria-labelledby="markdown-verification"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Markdown Verification </h2> <p>We use <a href="https://remark.js.org/">remark</a> to verify our markdown. You can easily run this tool simply by using our <code class="language-plaintext highlighter-rouge">npm</code> package:</p> <div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="go">npm install
|
|
npm run lint
|
|
</span></code></pre></div></div> <h2 id="language-mode"> <a href="#language-mode" class="anchor-heading" aria-labelledby="language-mode"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Language mode </h2> <ul> <li>Specifications SHOULD use formal technical language (<em>different from academic language</em>).</li> <li>Where appropriate, language SHOULD NOT use personal pronouns.</li> <li>Avoid using the <a href="https://en.wikipedia.org/wiki/English_passive_voice">passive voice</a> when being specific.</li> <li>In places where the passive voice is appropriate but makes the subject ambiguous, append the passive voice with “by <code class="language-plaintext highlighter-rouge">subject</code>”. Alternatively restructure the sentence to be in the active voice adding the sentence subject.</li> </ul> <p>For further reading on writing technical documents please read the Google Technical Writing article on <a href="https://developers.google.com/tech-writing/one/active-voice">Active voice vs. passive voice</a>.</p> <details> <summary>Examples:</summary> ### Personal pronouns Informal: >In this specification, **we** describe Formal: >This specification describes Informal: >If **you** want to run a Waku node and receive messages from Status clients, it must be properly configured. Formal: >A Waku node must be properly configured to receive messages from Status clients. ### Passive voice Passive voice: >a corresponding confirmation **is broadcast** by one or more peers Active voice: >**one or more peers broadcast** a corresponding confirmation In the case where the object of the sentence needs to be highlighted or given prominence the passive voice is appropriate. However, pay attention to not introduce an ambiguous subject if communicating specific information is your goal. ### Appropriate use of the passive voice >The Batch Acknowledge packet is followed by a keccak256 hash of the envelope's batch data (raw bytes). The subject of the sentence is "a keccak256 hash", but the sentence wants to highlight the Batch Acknowledge. ### Ambiguous subject In many cases sentences written in passive voice may be grammatically correct but hide that the sentence lacks a specified subject. Ambiguous: >A message confirmation **is sent** using Batch Acknowledge Active specific: >**A node sends** a message confirmation using Batch Acknowledge Passive specific: >A message confirmation **is sent by a node** using Batch Acknowledge Notice that the ambiguous sentence infers or omits the subject. Making it unclear what or who performs an action on the object of the sentence. In the example ambiguous sentence it is not stated what or who is sending a message confirmation. </details> </div> </div> <div class="search-overlay"></div> </div> </body> </html>
|