gem-graph-client/docs/GTK-docs/gnome-dev-documentation/developer.gnome.org/hig/guidelines/writing-style.html

334 lines
21 KiB
HTML
Raw Normal View History

<!doctype html>
<html class="no-js">
<head><meta charset="utf-8"/>
<meta name="viewport" content="width=device-width,initial-scale=1"/>
<meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<link rel="index" title="Index" href="../genindex.html" /><link rel="search" title="Search" href="../search.html" /><link rel="next" title="Typography" href="typography.html" /><link rel="prev" title="UI Styling" href="ui-styling.html" />
<meta name="generator" content="sphinx-4.3.0, furo 2021.07.05.beta38"/>
<title>Writing Style - GNOME Human Interface Guidelines documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../_static/styles/furo.css" />
<link rel="stylesheet" type="text/css" href="../_static/styles/furo-extensions.css" />
<link rel="stylesheet" type="text/css" href="../_static/gnome.css" />
<style>
:root {
--color-code-background: #f8f8f8;
--color-code-foreground: black;
--color-brand-primary: #4a86cf;
--color-brand-content: #4a86cf;
}
@media (prefers-color-scheme: dark) {
:root {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
}
/* For allowing end-user-specific overrides */
.override-light {
--color-code-background: #f8f8f8;
--color-code-foreground: black;
--color-brand-primary: #4a86cf;
--color-brand-content: #4a86cf;
}
.override-dark {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
</style><link media="(prefers-color-scheme: dark)" rel="stylesheet" href="../_static/pygments_dark.css"></head>
<body dir="">
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
<symbol id="svg-toc" viewBox="0 0 24 24">
<title>Contents</title>
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none"
stroke-width="1.5" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round">
<path stroke="none" d="M0 0h24v24H0z"/>
<line x1="4" y1="6" x2="20" y2="6" />
<line x1="10" y1="12" x2="20" y2="12" />
<line x1="6" y1="18" x2="20" y2="18" />
</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>
</svg>
<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
<label class="overlay sidebar-overlay" for="__navigation"></label>
<label class="overlay toc-overlay" for="__toc"></label>
<div class="page">
<header class="mobile-header">
<div class="header-left">
<label class="nav-overlay-icon" for="__navigation">
<i class="icon"><svg><use href="#svg-menu"></use></svg></i>
</label>
</div>
<div class="header-center">
<a href="../index.html"><div class="brand">GNOME Human Interface Guidelines</div></a>
</div>
<div class="header-right">
<label class="toc-overlay-icon toc-header-icon" for="__toc">
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
</label>
</div>
</header>
<aside class="sidebar-drawer">
<div class="sidebar-container">
<div class="sidebar-sticky"><a class="sidebar-brand centered" href="../index.html">
<div class="sidebar-logo-container">
<img class="sidebar-logo" src="../_static/logo.svg" alt="Logo"/>
</div>
<span class="sidebar-brand-text">GNOME Human Interface Guidelines</span>
</a><form class="sidebar-search-container" method="get" action="../search.html">
<input class="sidebar-search" placeholder=Search name="q">
<input type="hidden" name="check_keywords" value="yes">
<input type="hidden" name="area" value="default">
</form><div class="sidebar-scroll"><div class="sidebar-tree">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../principles.html">Design Principles</a></li>
<li class="toctree-l1"><a class="reference internal" href="../resources.html">Tools &amp; Resources</a></li>
<li class="toctree-l1 current has-children"><a class="reference internal" href="../guidelines.html">Guidelines</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label for="toctree-checkbox-1"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="app-naming.html">App Naming</a></li>
<li class="toctree-l2"><a class="reference internal" href="app-icons.html">App Icons</a></li>
<li class="toctree-l2"><a class="reference internal" href="pointer-touch.html">Pointer &amp; Touch</a></li>
<li class="toctree-l2"><a class="reference internal" href="keyboard.html">Keyboard</a></li>
<li class="toctree-l2"><a class="reference internal" href="ui-icons.html">UI Icons</a></li>
<li class="toctree-l2"><a class="reference internal" href="ui-styling.html">UI Styling</a></li>
<li class="toctree-l2 current current-page"><a class="current reference internal" href="#">Writing Style</a></li>
<li class="toctree-l2"><a class="reference internal" href="typography.html">Typography</a></li>
<li class="toctree-l2"><a class="reference internal" href="navigation.html">Navigation</a></li>
<li class="toctree-l2"><a class="reference internal" href="adaptive.html">Scaling &amp; Adaptiveness</a></li>
<li class="toctree-l2"><a class="reference internal" href="accessibility.html">Accessibility</a></li>
</ul>
</li>
<li class="toctree-l1 has-children"><a class="reference internal" href="../patterns.html">Patterns</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" type="checkbox"/><label for="toctree-checkbox-2"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l2 has-children"><a class="reference internal" href="../patterns/containers.html">Containers</a><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" type="checkbox"/><label for="toctree-checkbox-3"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../patterns/containers/windows.html">Windows</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/containers/header-bars.html">Header Bars</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/containers/popovers.html">Popovers</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/containers/utility-panes.html">Utility Panes</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/containers/boxed-lists.html">Boxed Lists</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/containers/grid-views.html">Grid Views</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/containers/list-column-views.html">List &amp; Column Views</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/containers/selection-mode.html">Selection &amp; Edit Modes</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../patterns/nav.html">Navigation</a><input class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" type="checkbox"/><label for="toctree-checkbox-4"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../patterns/nav/browsing.html">Browsing</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/nav/view-switchers.html">View Switchers</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/nav/tabs.html">Tabs</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/nav/sidebars.html">Sidebars</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/nav/search.html">Search</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../patterns/controls.html">Controls</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" type="checkbox"/><label for="toctree-checkbox-5"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/buttons.html">Buttons</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/menus.html">Menus</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/switches.html">Switches</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/text-fields.html">Text Fields</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/checkboxes.html">Checkboxes</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/radio-buttons.html">Radio Buttons</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/drop-downs.html">Drop-Down Lists</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/sliders.html">Sliders</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/spin-buttons.html">Spin Buttons</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/controls/overlaid.html">Overlaid Controls</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../patterns/feedback.html">Feedback</a><input class="toctree-checkbox" id="toctree-checkbox-6" name="toctree-checkbox-6" type="checkbox"/><label for="toctree-checkbox-6"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../patterns/feedback/notifications.html">Notifications</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/feedback/toasts.html">Toasts</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/feedback/info-bars.html">Info Bars</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/feedback/progress-bars.html">Progress Bars</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/feedback/spinners.html">Spinners</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/feedback/dialogs.html">Dialogs</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/feedback/placeholders.html">Placeholder Pages</a></li>
<li class="toctree-l3"><a class="reference internal" href="../patterns/feedback/tooltips.html">Tooltips</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1 has-children"><a class="reference internal" href="../reference.html">Reference</a><input class="toctree-checkbox" id="toctree-checkbox-7" name="toctree-checkbox-7" type="checkbox"/><label for="toctree-checkbox-7"><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l2"><a class="reference internal" href="../reference/keyboard.html">Standard Keyboard Shortcuts</a></li>
<li class="toctree-l2"><a class="reference internal" href="../reference/palette.html">Palette</a></li>
<li class="toctree-l2"><a class="reference internal" href="../reference/backgrounds.html">Backgrounds</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</div>
</aside>
<main class="main">
<div class="content">
<article role="main">
<label class="toc-overlay-icon toc-content-icon" for="__toc">
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
</label>
<section id="writing-style">
<h1>Writing Style<a class="headerlink" href="#writing-style" title="Permalink to this headline"></a></h1>
<p>Text plays an important role in user interfaces. Take the time to ensure that any text you use is clearly written, easy to understand, and looks good.</p>
<section id="guidelines">
<h2>Guidelines<a class="headerlink" href="#guidelines" title="Permalink to this headline"></a></h2>
<p>Your main goal should be to ensure that text is easy to understand and quick to read.</p>
<ul class="simple">
<li><p>Keep text short and to the point. This improves speed of comprehension for the user. It also reduces the expansion of text when translated (remember that translated English text can expand up to 30% in some languages).</p></li>
<li><p>Do not shorten your text to the point of losing meaning. A three-word label that provides clear information is better than a one-word label that is ambiguous or vague. Try to find the fewest possible words to satisfactorily convey the meaning of your label.</p></li>
<li><p>Use words, phrases, and concepts that are familiar to the people who will be using your application, rather than terms from the underlying system. This may mean using terms that are associated with the tasks your application supports. For example, in medicine, the paper folder that contains patient information is called a “chart”. Hence, a medical application might refer to a patient record as a “chart” rather than as a “patient database record”.</p></li>
<li><p>Text should adopt a neutral tone and speak from the point of view of the software. Pronouns like “you” or “my” should be avoided wherever possible. However, if it is impossible to avoid referring to something as belonging to the user, “your” is preferable to “my”. For example, “Your Records”.</p></li>
<li><p>Use the standard GNOME terms when referring to parts of the user interface, such as “pointer” and “window”. The HIG can be used as a reference in this regard.</p></li>
<li><p>Avoid repetition where possible.</p></li>
<li><p>Sentences should not be constructed from text in several controls. Sentences that run from one control to another will often not make sense when translated into other languages.</p></li>
<li><p>Latin abbreviations such as “i.e.” or “e.g.” should be avoided, since they cant always be easily translated and can be unintelligible when read by screen readers. Instead, use full words like “for example”.</p></li>
</ul>
</section>
<section id="capitalization">
<h2>Capitalization<a class="headerlink" href="#capitalization" title="Permalink to this headline"></a></h2>
<p>Two styles of capitalization are used in GNOME user interfaces: header capitalization and sentence capitalization.</p>
<section id="header-capitalization">
<span id="id1"></span><h3>Header Capitalization<a class="headerlink" href="#header-capitalization" title="Permalink to this headline"></a></h3>
<p>Header capitalization should be used for any headings, including headings in header bars, tab titles, and view titles. It should also be used for short control labels that do not normally form proper sentences, such as button labels, switch labels and menu items.</p>
<p>Header capitalization should capitalize the first letter of:</p>
<ul class="simple">
<li><p>All words with four or more letters.</p></li>
<li><p>Verbs of any length, such as “Be”, “Are”, “Is”, “See” and “Add”.</p></li>
<li><p>The first and last word.</p></li>
<li><p>Hyphenated words; for example: “Self-Test” or “Post-Install”.</p></li>
</ul>
<p>For example: “Create a Document”, “Find and Replace”, “Document Cannot Be Found”.</p>
</section>
<section id="sentence-capitalization">
<span id="id2"></span><h3>Sentence Capitalization<a class="headerlink" href="#sentence-capitalization" title="Permalink to this headline"></a></h3>
<p>Sentence capitalization should be used for labels that form sentences or that run on to other text, including labels for check boxes, radio buttons, sliders, text entry boxes, field labels and combobox labels. It should also be used for explanatory or body text, such as in dialogs or notifications.</p>
<p>Capitalize the first letter of the first word and any words that are normally capitalized in sentences, such as proper nouns.</p>
<p>For example: “The document cannot be found in this location.” “Finding results for London.”</p>
</section>
</section>
<section id="headings">
<span id="informal-headings"></span><h2>Headings<a class="headerlink" href="#headings" title="Permalink to this headline"></a></h2>
<p>Headings are written in a concise form and do not form complete sentences. As part of this, auxillary verbs, such as “have” and “is”, are often omitted. So are articles, like “a”, “an”, “the”.</p>
<p>For example, a heading would typically be written as “Three Documents Updated”, as opposed to “Three Documents Have Been Updated”.</p>
<p>Headings typically use header capitalization and a heavy font style.</p>
<section id="id3">
<h3>Informal Headings<a class="headerlink" href="#id3" title="Permalink to this headline"></a></h3>
<p>When a heading exists without accompanying information, it can be useful to express it as a full sentence. In this case:</p>
<ul class="simple">
<li><p>Write the heading as a sentence, including auxillary verbs and articles.</p></li>
<li><p>Use sentence capitalization.</p></li>
<li><p>Omit the period from the end of the sentence.</p></li>
<li><p>Continue to use a bold font style.</p></li>
</ul>
<p>This heading style should not be used in the majority of cases, but when it is used, it can help to give a more informal feel.</p>
</section>
</section>
<section id="ellipses">
<span id="id4"></span><h2>Ellipses (…)<a class="headerlink" href="#ellipses" title="Permalink to this headline"></a></h2>
<p>Use an ellipsis (…) at the end of a label if further input or confirmation is required from the user before the action can be carried out. For example, <em>Save As…</em>, <em>Find…</em> or <em>Delete…</em>.</p>
<p>Do not add an ellipsis to labels such as <em>Properties</em> or <em>Preferences</em>. While these commands open windows that can incorporate further functionality, the label does not specify an action, and therefore does not need to communicate that further input or confirmation is required.</p>
</section>
</section>
</article>
<footer>
<div class="related-pages">
<a class="next-page" href="typography.html">
<div class="page-info">
<div class="context">
<span>Next</span>
</div>
<div class="title">Typography</div>
</div>
<svg><use href="#svg-arrow-right"></use></svg>
</a>
<a class="prev-page" href="ui-styling.html">
<svg><use href="#svg-arrow-right"></use></svg>
<div class="page-info">
<div class="context">
<span>Previous</span>
</div>
<div class="title">UI Styling</div>
</div>
</a>
</div>
</footer>
</div>
<aside class="toc-drawer">
<div class="toc-sticky toc-scroll">
<div class="toc-title-container">
<span class="toc-title">
Contents
</span>
</div>
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">Writing Style</a><ul>
<li><a class="reference internal" href="#guidelines">Guidelines</a></li>
<li><a class="reference internal" href="#capitalization">Capitalization</a><ul>
<li><a class="reference internal" href="#header-capitalization">Header Capitalization</a></li>
<li><a class="reference internal" href="#sentence-capitalization">Sentence Capitalization</a></li>
</ul>
</li>
<li><a class="reference internal" href="#headings">Headings</a><ul>
<li><a class="reference internal" href="#id3">Informal Headings</a></li>
</ul>
</li>
<li><a class="reference internal" href="#ellipses">Ellipses (…)</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</aside>
</main>
</div><script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/scripts/main.js"></script>
</body>
</html>