gem-graph/gem-graph-client
gem-graph
/
gem-graph-client
3
0
Fork 0
Code Issues 14 Pull Requests Projects Releases Activity
gem-graph-client/doc/GTK-docs/gnome-dev-documentation/developer.gnome.org/documentation/guidelines/devel-docs.html

689 lines
43 KiB
HTML
Raw Normal View History

cleaning under doxygen control: one_rule/algebra
2024-10-18 09:43:30 +02:00
<!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="Tutorials" href="../tutorials.html" /><link rel="prev" title="Integrating with GNOME" href="maintainer/integrating.html" />
<meta name="generator" content="sphinx-4.3.0, furo 2022.06.21"/>
<title>Developer Documentation Style Guidelines - GNOME Developer Documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../_static/styles/furo.css?digest=40978830699223671f4072448e654b5958f38b89" />
<link rel="stylesheet" type="text/css" href="../_static/tabs.css" />
<link rel="stylesheet" type="text/css" href="../_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
<link rel="stylesheet" type="text/css" href="../_static/gnome.css" />
<style>
body {
--color-code-background: #f8f8f8;
--color-code-foreground: black;
--color-brand-primary: #4a86cf;
--color-brand-content: #4a86cf;
}
@media not print {
body[data-theme="dark"] {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
@media (prefers-color-scheme: dark) {
body:not([data-theme="light"]) {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
}
}
}
</style></head>
<body>
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
<symbol id="svg-toc" viewBox="0 0 24 24">
<title>Contents</title>
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
<path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/>
</svg>
</symbol>
<symbol id="svg-menu" viewBox="0 0 24 24">
<title>Menu</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="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" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
<polyline points="9 18 15 12 9 6"></polyline>
</svg>
</symbol>
<symbol id="svg-sun" viewBox="0 0 24 24">
<title>Light mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
<circle cx="12" cy="12" r="5"></circle>
<line x1="12" y1="1" x2="12" y2="3"></line>
<line x1="12" y1="21" x2="12" y2="23"></line>
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
<line x1="1" y1="12" x2="3" y2="12"></line>
<line x1="21" y1="12" x2="23" y2="12"></line>
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
</svg>
</symbol>
<symbol id="svg-moon" viewBox="0 0 24 24">
<title>Dark mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
<path stroke="none" d="M0 0h24v24H0z" fill="none" />
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
</svg>
</symbol>
<symbol id="svg-sun-half" viewBox="0 0 24 24">
<title>Auto light/dark mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-shadow">
<path stroke="none" d="M0 0h24v24H0z" fill="none"/>
<circle cx="12" cy="12" r="9" />
<path d="M13 12h5" />
<path d="M13 15h4" />
<path d="M13 18h1" />
<path d="M13 9h4" />
<path d="M13 6h1" />
</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 Developer Documentation</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" href="../index.html">
<span class="sidebar-brand-text">GNOME Developer Documentation</span>
</a><form class="sidebar-search-container" method="get" action="../search.html" role="search">
<input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
<input type="hidden" name="check_keywords" value="yes">
<input type="hidden" name="area" value="default">
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<p class="caption" role="heading"><span class="caption-text">Contents</span></p>
<ul class="current">
<li class="toctree-l1 has-children"><a class="reference internal" href="../introduction.html">Platform Introduction</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle child pages in navigation</div><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="../introduction/components.html">Platform Components</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../introduction/overview/libraries.html">Libraries</a></li>
<li class="toctree-l3"><a class="reference internal" href="../introduction/overview/services.html">Services</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../introduction/languages.html">Programming Languages</a></li>
<li class="toctree-l2"><a class="reference internal" href="../introduction/builder.html">GNOME Builder</a></li>
<li class="toctree-l2"><a class="reference internal" href="../introduction/flatpak.html">Flatpak</a></li>
</ul>
</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-3" name="toctree-checkbox-3" role="switch" type="checkbox"/><label for="toctree-checkbox-3"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul class="current">
<li class="toctree-l2 has-children"><a class="reference internal" href="programming.html">Programming Guidelines</a><input class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" role="switch" type="checkbox"/><label for="toctree-checkbox-4"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="programming/coding-style.html">C Coding Style</a></li>
<li class="toctree-l3"><a class="reference internal" href="programming/memory-management.html">Managing Memory</a></li>
<li class="toctree-l3"><a class="reference internal" href="programming/writing-good-code.html">The Importance of Writing Good Code</a></li>
<li class="toctree-l3"><a class="reference internal" href="programming/optimizing.html">Optimizing GNOME Applications</a></li>
<li class="toctree-l3"><a class="reference internal" href="programming/namespacing.html">Namespacing</a></li>
<li class="toctree-l3"><a class="reference internal" href="programming/introspection.html">Introspection</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="accessibility.html">Accessibility</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" role="switch" type="checkbox"/><label for="toctree-checkbox-5"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="accessibility/coding-guidelines.html">Coding Guidelines for Supporting Accessibility</a></li>
<li class="toctree-l3"><a class="reference internal" href="accessibility/custom-widgets.html">Making Custom Components Accessible</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="localization.html">Localization</a><input class="toctree-checkbox" id="toctree-checkbox-6" name="toctree-checkbox-6" role="switch" type="checkbox"/><label for="toctree-checkbox-6"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="localization/practices.html">Best Practices for Localization</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="maintainer.html">Maintainer Guidelines</a><input class="toctree-checkbox" id="toctree-checkbox-7" name="toctree-checkbox-7" role="switch" type="checkbox"/><label for="toctree-checkbox-7"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="maintainer/api-stability.html">API Stability</a></li>
<li class="toctree-l3"><a class="reference internal" href="maintainer/parallel-installability.html">Parallel Installability</a></li>
<li class="toctree-l3"><a class="reference internal" href="maintainer/integrating.html">Integrating with GNOME</a></li>
</ul>
</li>
<li class="toctree-l2 current current-page"><a class="current reference internal" href="#">Developer Documentation Style Guidelines</a></li>
</ul>
</li>
<li class="toctree-l1 has-children"><a class="reference internal" href="../tutorials.html">Tutorials</a><input class="toctree-checkbox" id="toctree-checkbox-8" name="toctree-checkbox-8" role="switch" type="checkbox"/><label for="toctree-checkbox-8"><div class="visually-hidden">Toggle child pages in navigation</div><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="../tutorials/beginners.html">Beginners Tutorials</a><input class="toctree-checkbox" id="toctree-checkbox-9" name="toctree-checkbox-9" role="switch" type="checkbox"/><label for="toctree-checkbox-9"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l3 has-children"><a class="reference internal" href="../tutorials/beginners/getting_started.html">Getting Started</a><input class="toctree-checkbox" id="toctree-checkbox-10" name="toctree-checkbox-10" role="switch" type="checkbox"/><label for="toctree-checkbox-10"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/getting_started/content_view.html">Adding A Content View</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/getting_started/opening_files.html">Loading Content From A File</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/getting_started/cursor_position.html">Showing The Cursor Position</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/getting_started/saving_files.html">Saving The Content To A File</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/getting_started/saving_state.html">Saving The Application State</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/getting_started/adding_toasts.html">Notifying The User With Toasts</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/getting_started/dark_mode.html">Forcing The Dark Color Scheme</a></li>
</ul>
</li>
<li class="toctree-l3 has-children"><a class="reference internal" href="../tutorials/beginners/components.html">UI components</a><input class="toctree-checkbox" id="toctree-checkbox-11" name="toctree-checkbox-11" role="switch" type="checkbox"/><label for="toctree-checkbox-11"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/window.html">Windows</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/image.html">Images</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/label.html">Labels</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/button.html">Buttons</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/box.html">Boxes</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/stack.html">Stacks</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/leaflet.html">Leaflets</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/toggle.html">Toggles</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/check_box.html">Check Boxes</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/radio_button.html">Radio Buttons</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/spin_button.html">Spin Buttons</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/link_button.html">Link Buttons</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/switch.html">Switches</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/menu_button.html">Menu Buttons</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/entry.html">Entries</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/password_entry.html">Password Entries</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/message_dialog.html">Messages</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/file_dialog.html">File Dialogs</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/spinner.html">Spinners</a></li>
<li class="toctree-l4"><a class="reference internal" href="../tutorials/beginners/components/level_bar.html">Level Bars</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials/application-id.html">Application ID</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials/application.html">Using GtkApplication</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials/save-state.html">Saving and Loading Window State</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials/notifications.html">Using Notifications</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials/themed-icons.html">Themed Icons</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials/deprecations.html">Dealing With Deprecations</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials/actions.html">Actions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials/menus.html">Menus</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials/search-provider.html">Writing a Search Provider</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials/pre-and-post-conditions.html">Pre- and Post-Conditions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials/main-contexts.html">Main Contexts</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials/lists.html">Using GLib Lists</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials/threading.html">Threading</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials/asynchronous-programming.html">Asynchronous Programming</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials/drag-and-drop.html">Drag and Drop</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials/widget-templates.html">Widget Templates</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="developer-documentation-style-guidelines">
<h1>Developer Documentation Style Guidelines<a class="headerlink" href="#developer-documentation-style-guidelines" title="Permalink to this headline">#</a></h1>
<section id="motivation">
<h2>Motivation<a class="headerlink" href="#motivation" title="Permalink to this headline">#</a></h2>
<p>In order to create a consistent platform, GNOME modules must have a consistent
documentation not just in terms of content, but also in terms of style. A
singular editorial voice helps in creating high-quality, readable, and
consistent documentation.</p>
<p>This style guide encodes the style used by the GNOME documentation for
developers; it does not claim to be objectively better than other style guides.
The rules in this guide are not meant to be absolute: you should have readable
documentation, first and foremost; if the result is not readable, you should
exercise your own judgement.</p>
<p>It is important to note that this style guide is a living document: context and
recommendations may change over time, and these guidelines will change as well.
You should check the <a class="reference internal" href="#whatsnew"><span class="std std-ref">What’s new</span></a> section of this document for
changes.</p>
</section>
<section id="voice-and-tone">
<h2>Voice and tone<a class="headerlink" href="#voice-and-tone" title="Permalink to this headline">#</a></h2>
<p>The documentation should use a friendly, conversational voice. Be respectful and
approachable. Be straightforward, and clear, without being pedantic and pushy;
like a friend helping somebody out in their time of need.</p>
<ul class="simple">
<li><p><strong>Get to the point</strong>. Make sure to present the key information first; put it
in the most noticeable spot. Make steps and choices obvious. Give all the
necessary information up front. Do not get in the way.</p></li>
<li><p><strong>Talk like a person</strong>. Write colloquially, without being cutesy. Don’t write
exactly how you would speak, but feel free to use everyday words and
contractions. Don’t use jargon and acronyms when explaining things. Don’t use
pop culture references or inside jokes. Developer documentation is technical,
but you can still be human. Be personal and memorable, and you can be funny
when needed.</p></li>
<li><p><strong>Keep it simple</strong>. Don’t be unnecessarily verbose or pedantic. Write short
sentences that are easy to scan and read. Break up explanations, and layer
the information so that people can stop once they found out what they need.</p></li>
</ul>
<p>For developer documentation you can assume that the reader is going to be
knowledgeable, but remember that there are varying levels of proficiency; your
goal is to allow developers to achieve their goals.</p>
<section id="some-things-to-avoid">
<h3>Some things to avoid<a class="headerlink" href="#some-things-to-avoid" title="Permalink to this headline">#</a></h3>
<ul class="simple">
<li><p>Buzzwords and jargon</p></li>
<li><p>Ableist language</p></li>
<li><p>Placeholder phrases, like <em>please note</em> and <em>at this time</em></p></li>
<li><p>Long-winded sentences</p></li>
<li><p>Starting all sentences in the same way, e.g. <em>You can</em> or <em>To do</em></p></li>
<li><p>Jokes at the expense of other projects, or people using them</p></li>
<li><p>Pop culture references</p></li>
<li><p>Community inside jokes</p></li>
<li><p>Exclamation marks</p></li>
<li><p>Mixing metaphors</p></li>
<li><p>Obscure implementation details</p></li>
<li><p>Phrases like <em>simply</em>, <em>it is simple to</em>, <em>it’s easy to</em>, <em>just</em>, <em>quickly</em></p></li>
<li><p>Internet slang, like <em>tl;dr</em> or <em>ymmv</em></p></li>
<li><p>Excessive use of <em>please</em>, e.g. <em>please view this document</em> or <em>please use
this class</em></p></li>
</ul>
</section>
</section>
<section id="writing-inclusively">
<h2>Writing inclusively<a class="headerlink" href="#writing-inclusively" title="Permalink to this headline">#</a></h2>
<p>GNOME strives to be an inclusive community. Our developer documentation should
reflect that committment.</p>
<section id="global-audience">
<h3>Global audience<a class="headerlink" href="#global-audience" title="Permalink to this headline">#</a></h3>
<p>GNOME users and contributors live and work all over the world, and you can
assume that the documentation will be read by people whose first language is not
English.</p>
<ul class="simple">
<li><p><strong>Write short sentences</strong>. Consider breaking sentences with multiple clauses
and commas into multiple sentences.</p></li>
<li><p><strong>Use list and tables</strong>. If you have multiple paragraphs and complex
sentences, consider using list and tables instead.</p></li>
<li><p><strong>Use sentence-style capitalization</strong>. Capitalize proper nouns only, including
trademarks and name of projects and products.</p></li>
<li><p><strong>Avoid idioms, colloquial expressions, and culture-specific references</strong>.</p></li>
<li><p><strong>Avoid stacking modifiers</strong>. Long chains of modifying words are confusing,
even to native English speakers.</p></li>
<li><p><strong>Use active voice</strong>.</p></li>
<li><p><strong>Keep adjective and adverbs close to the word they modify</strong>.</p></li>
<li><p><strong>Use “that”, “who”, and “which” to clarify sentence structure</strong>.</p></li>
</ul>
</section>
<section id="gender-identity-and-pronouns">
<h3>Gender identity and pronouns<a class="headerlink" href="#gender-identity-and-pronouns" title="Permalink to this headline">#</a></h3>
<p>Do not use gender-specific pronouns unless the person you’re referring to is
actually that gender.</p>
<p>In particular, do not use <em>he</em>, <em>him</em>, <em>she</em>, or <em>her</em> as gender-neutral
pronouns, and do not use <em>he/she</em>, <em>(s)he</em>, or <em>he or she</em> or other similar
compound approaches. Instead, use the <a class="reference external" href="https://public.oed.com/blog/a-brief-history-of-singular-they/">singular “they”</a>.</p>
<p>Avoid first-person pronouns (<em>I</em>, <em>we</em>, <em>us</em>, <em>our</em>, <em>ours</em>), except:</p>
<ul class="simple">
<li><p>questions in a “frequently asked questions” document</p></li>
<li><p>a document written explicitly in first person</p></li>
<li><p>a sentence referring to your project or organization</p></li>
</ul>
<p>Always use the second-person pronoun wherever possible.</p>
<p>For relative pronouns, always make use of <em>that</em>, <em>which</em>, and <em>who</em> to clarify
the sentence structure. <em>That</em> and <em>which</em> are not interchangeable:</p>
<ul class="simple">
<li><p><em>That</em> introduces a restrictive clause, and isn’t preceded by a comma</p></li>
<li><p><em>Which</em> introduces a non-restrictive clause, and is preceded by a comma</p></li>
</ul>
<p>When referring to a person, always use <em>who</em>.</p>
<p>When referring to groups of people, animals, or things you can use <em>whose</em>.</p>
</section>
<section id="avoiding-bias-in-communication">
<h3>Avoiding bias in communication<a class="headerlink" href="#avoiding-bias-in-communication" title="Permalink to this headline">#</a></h3>
<ul class="simple">
<li><p><strong>When writing examples, be mindful of stereotypes</strong>. Choose names, gender
identities, and cultural backgrounds to reflect a variety of cases.</p></li>
<li><p><strong>Do not make generalizations about people, countries, regions, and
cultures</strong>.</p></li>
<li><p><strong>Don’t use slang</strong>.</p></li>
<li><p><strong>Don’t use profane or derogatory terms</strong>.</p></li>
<li><p><strong>Don’t use terms that carry racial bias</strong>. For instance, do not use terms
like <em>master/slave</em>. Use <em>primary/secondary</em> or <em>physical/logical</em>, depending
on the context. Instead of replacing a word you can also rewrite to improve
the clarity of a sentence; for instance, instead of replacing <em>whitelist</em> with
<em>allowlist</em>, you can explain what is allowed.</p></li>
<li><p><strong>Focus on people, not disabilities</strong>. Do not describe people without
disabilities using terms like <em>normal</em> or <em>healthy</em>; avoid euphemisms, like
<em>special</em> or <em>differently able</em>; avoid terms that remove personhood, like
<em>quadriplegic</em>, and instead use <em>quadriplegic person</em>.</p></li>
<li><p><strong>Use inclusive language</strong>.</p></li>
</ul>
</section>
</section>
<section id="formatting">
<h2>Formatting<a class="headerlink" href="#formatting" title="Permalink to this headline">#</a></h2>
<section id="dates-and-times">
<h3>Dates and times<a class="headerlink" href="#dates-and-times" title="Permalink to this headline">#</a></h3>
<p>When expressing times use the 12-hour clock, except in cases where the 24-hour
clock is required:</p>
<ul class="simple">
<li><p>use exact times, in the <code class="docutils literal notranslate"><span class="pre">HH:MM</span></code> format</p></li>
<li><p>always capitalize AM and PM</p></li>
<li><p>remove the minutes for round hours</p></li>
</ul>
<p>For ranges, use hyphens without spaces, for instance: <em>5-10 minutes ago</em>.</p>
<p>Avoid specifying time zones unless absolutely necessary; use the full name of
the time zone, adding the offset from UTC as a parenthetical, for instance:</p>
<ul class="simple">
<li><p>US Pacific Standard Time (UTC-8)</p></li>
<li><p>Central European Summer Time (UTC+2)</p></li>
</ul>
<p>When expressing dates:</p>
<ul class="simple">
<li><p>use the name of months and days of the week in full, with the month followed
by the day of the month, a comma, and the full four-digits year</p></li>
<li><p>for numeric only dates, use the <code class="docutils literal notranslate"><span class="pre">YYYY-MM-DD</span></code> format conforming to the
ISO-8601 standard</p></li>
</ul>
</section>
<section id="numbers">
<h3>Numbers<a class="headerlink" href="#numbers" title="Permalink to this headline">#</a></h3>
<ul class="simple">
<li><p>When using ordinal numbers, spell them out in text: first, second, tenth,
twenty-first.</p></li>
<li><p>Spell out numbers between zero and nine.</p></li>
<li><p>Spell out numbers at the beginning of a sentence.</p></li>
<li><p>Use numerals for negative numbers, fractions, percentages, dimensions, and
decimals.</p></li>
</ul>
</section>
<section id="capitalization">
<h3>Capitalization<a class="headerlink" href="#capitalization" title="Permalink to this headline">#</a></h3>
<ul class="simple">
<li><p>Use title-style capitalization only for top level titles, and sentence-style
capitalization for everything else:</p>
<ul>
<li><p>Capitalize the first word of a sentence</p></li>
<li><p>Use lowercase for every other word</p></li>
<li><p>When words are joined by a slash, capitalize the second word if the first is
also capitalized</p></li>
</ul>
</li>
<li><p>Never use all uppercase for emphasis.</p></li>
<li><p>Do not use all lowercase as a style choice.</p></li>
<li><p>Do not use internal capitalization, unless it’s a brand name.</p></li>
<li><p>Do not capitalize a spelled-out acronym, unless it’s a brand name or a proper
noun.</p></li>
</ul>
</section>
</section>
<section id="writing-api-references">
<h2>Writing API references<a class="headerlink" href="#writing-api-references" title="Permalink to this headline">#</a></h2>
<p>When you are documenting an API, you should provide a complete reference,
typically by generating it from the source code through documentation comments.</p>
<section id="basics">
<h3>Basics<a class="headerlink" href="#basics" title="Permalink to this headline">#</a></h3>
<p>An API reference <strong>must</strong> provide a description of:</p>
<ul class="simple">
<li><p>every type: classes, structures, unions, interfaces, and enumerations</p></li>
<li><p>every public field inside classes, unions, and structures</p></li>
<li><p>every virtual function inside classes and interfaces</p></li>
<li><p>every member of an enumeration</p></li>
<li><p>every constant</p></li>
<li><p>every function and method</p></li>
<li><p>every signal and property defined by a class or an interface</p></li>
</ul>
<p>For every type there should be a short (25-50 lines of code) example on how to
use the type.</p>
</section>
<section id="typography">
<h3>Typography<a class="headerlink" href="#typography" title="Permalink to this headline">#</a></h3>
<ul class="simple">
<li><p>All type, function, signal, and property names should use <code class="docutils literal notranslate"><span class="pre">code</span> <span class="pre">style</span></code>.</p></li>
<li><p>String literals, like XML elements and attributes, should use <code class="docutils literal notranslate"><span class="pre">code</span> <span class="pre">style</span></code>.</p></li>
<li><p>Parameters for functions, methods, and signals should be in <em>italics</em>.</p></li>
<li><p>Type names in the documentation should match the type name in the code</p>
<ul>
<li><p>Make sure not to pluralize the type name. For instance, do not use
<code class="docutils literal notranslate"><span class="pre">GtkButtons</span></code>, and use “<code class="docutils literal notranslate"><span class="pre">GtkButton</span></code> instances” instead</p></li>
</ul>
</li>
</ul>
</section>
<section id="classes-structures-interfaces-enumerations">
<h3>Classes, structures, interfaces, enumerations<a class="headerlink" href="#classes-structures-interfaces-enumerations" title="Permalink to this headline">#</a></h3>
<p>Begin the description of a type with a short, unique sentence, briefly stating
the purpose of the type, especially if it cannot be immediately deduced by the
name of the type itself.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The first sentence will typically be used as a summary inside the indices, so
it should be in the range of 10-12 words.</p>
</div>
<ul class="simple">
<li><p>Do not repeat the name of the type in the first sentence.</p></li>
<li><p>Do not say <em>this class does…</em> or <em>this type will…</em>.</p></li>
</ul>
<p>For classes and structures that have public fields, keep the description of each
field as brief as possible.</p>
</section>
<section id="callable-symbols">
<h3>Callable symbols<a class="headerlink" href="#callable-symbols" title="Permalink to this headline">#</a></h3>
<p>The documentation for callable symbols like methods, functions, and signals
should briefly state the action performed; state the prerequisites and side
effects; detail what kind of errors may be raised; and specify any related API.</p>
<p>You should use the present tense for all descriptions.</p>
<ul class="simple">
<li><p><strong>Description</strong>. The description should start with a verb describing the
operation, using the name of the symbol as the unstated subject: <em>Adds a
label widget to the notebook page</em>.</p>
<ul>
<li><p>If the symbol is a getter function and it returns a boolean value,
start with <em>Checks whether…</em></p></li>
<li><p>If the symbol is a getter function and returns something other than a
boolean value, start with <em>Gets the…</em> or <em>Retrieves the…</em></p></li>
<li><p>If the symbol is a setter function, start with <em>Sets the…</em></p></li>
<li><p>If the symbol updates some state, start with <em>Updates the…</em></p></li>
<li><p>If the symbol deletes something, start with <em>Deletes the…</em>
or <em>Removes the…</em></p></li>
<li><p>For constructors, start with <em>Creates a new…</em></p></li>
<li><p>For callbacks, start with <em>Called by…</em></p></li>
</ul>
</li>
<li><p><strong>Parameters</strong>. Be as brief as possible in the description. Put any detailed
information in the callable’s description.</p>
<ul>
<li><p>Start the parameter description with a lower case word</p></li>
<li><p>Do not end the description with a period</p></li>
<li><p>Start the parameter description with “a” or “the”</p></li>
<li><p>Do not repeat the type of the parameter</p></li>
<li><p>For boolean parameters that describe an action, start the sentence
with <em>if true…</em> or <em>if false…</em></p></li>
<li><p>For boolean parameters that describe a state, use the format <em>true if…; false otherwise</em>
* In these contexts, do not capitalize “true” and “false”, and do not use
<code class="docutils literal notranslate"><span class="pre">code</span> <span class="pre">style</span></code> with constants</p></li>
<li><p>Do not include <em>or NULL</em> in the description of nullable parameters</p></li>
<li><p>For parameters using variadic arguments, use the format <em>a list of…</em></p></li>
</ul>
</li>
<li><p><strong>Return values</strong>. Be as brief as possible in the description. Put any
detailed information in the callable’s description.</p>
<ul>
<li><p>For boolean return values, use the format <em>true if…; false otherwise</em></p></li>
<li><p>For any other type, start with <em>The…</em></p></li>
<li><p>Do not include <em>or NULL</em> in the description of nullable return values</p></li>
</ul>
</li>
<li><p><strong>Errors</strong>. If the function sets a <code class="docutils literal notranslate"><span class="pre">GError</span></code> make sure to include the
domains and codes that are going to be set in case of error in the
callable’s description.</p></li>
</ul>
</section>
<section id="properties">
<h3>Properties<a class="headerlink" href="#properties" title="Permalink to this headline">#</a></h3>
<p>When describing properties include the same information as the setter and getter
functions:</p>
<ul class="simple">
<li><p><strong>preconditions</strong>, like range of valid values</p></li>
<li><p><strong>side effects</strong>, for instance updating a property causes another read-only
property to change state and emit a notification</p></li>
<li><p><strong>default value</strong>, in case an object determines the initial state depending
on whether the property was set at construction time or not</p></li>
</ul>
</section>
<section id="code-examples">
<h3>Code examples<a class="headerlink" href="#code-examples" title="Permalink to this headline">#</a></h3>
<p>Code examples should illustrate how to use a specific API in the most idiomatic
way possible. You might use:</p>
<ul class="simple">
<li><p>one-line examples interspersed with text</p></li>
<li><p>short, self-contained examples presenting a single feature</p></li>
<li><p>long examples, presenting multiple features</p></li>
</ul>
<p>Provide an introduction about what the example does, and what requirements and
preconditions it has.</p>
<p>Many developers will copy the examples you provide, and use them as a basis for
their own needs. Design code for reuse, and leave comments on what to modify.</p>
<p>Do not include complicated or convoluted code; make examples easy to scan and
follow. Complex examples can be part of tutorials or deep dive articles.</p>
<p>Do not state the obvious inside the comments.</p>
<p>If you have elided a portion of an example for the sake of brevity, make sure to
provide a comment that explains what you removed.</p>
<p>Show the expected output, using images if needed.</p>
<p>Always compile and test the example code.</p>
<p>Make sure the example code follows the best practices for accessibility and
security.</p>
</section>
<section id="deprecations">
<h3>Deprecations<a class="headerlink" href="#deprecations" title="Permalink to this headline">#</a></h3>
<p>Whenever some symbol or type is deprecated, specify the replacement and the
version in which the deprecation occurred. If there is no direct replacement,
describe how the reader can achieve a similar result.</p>
</section>
</section>
<section id="what-s-new">
<span id="whatsnew"></span><h2>What’s new<a class="headerlink" href="#what-s-new" title="Permalink to this headline">#</a></h2>
<p>In this section we will list the changes in the style guidelines, so you can
easily follow along.</p>
</section>
<section id="related-resources">
<h2>Related resources<a class="headerlink" href="#related-resources" title="Permalink to this headline">#</a></h2>
<ul class="simple">
<li><p><a class="reference external" href="https://docs.microsoft.com/en-gb/style-guide/welcome/">Microsoft Writing Style Guide</a></p></li>
<li><p><a class="reference external" href="https://developers.google.com/style">Google developer documentation style guide</a></p></li>
<li><p><a class="reference external" href="https://help.apple.com/applestyleguide/">Apple Style Guide</a></p></li>
<li><p><a class="reference external" href="https://stylepedia.net/">Red Hat Technical Writing Style Guide</a></p></li>
<li><p><a class="reference external" href="https://www.gov.uk/guidance/writing-api-reference-documentation">Gov.UK Writing API reference documentation</a></p></li>
</ul>
</section>
</section>
</article>
<footer>
<div class="related-pages">
<a class="next-page" href="../tutorials.html">
<div class="page-info">
<div class="context">
<span>Next</span>
</div>
<div class="title">Tutorials</div>
</div>
<svg><use href="#svg-arrow-right"></use></svg>
</a>
<a class="prev-page" href="maintainer/integrating.html">
<svg><use href="#svg-arrow-right"></use></svg>
<div class="page-info">
<div class="context">
<span>Previous</span>
</div>
<div class="title">Integrating with GNOME</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="#">Developer Documentation Style Guidelines</a><ul>
<li><a class="reference internal" href="#motivation">Motivation</a></li>
<li><a class="reference internal" href="#voice-and-tone">Voice and tone</a><ul>
<li><a class="reference internal" href="#some-things-to-avoid">Some things to avoid</a></li>
</ul>
</li>
<li><a class="reference internal" href="#writing-inclusively">Writing inclusively</a><ul>
<li><a class="reference internal" href="#global-audience">Global audience</a></li>
<li><a class="reference internal" href="#gender-identity-and-pronouns">Gender identity and pronouns</a></li>
<li><a class="reference internal" href="#avoiding-bias-in-communication">Avoiding bias in communication</a></li>
</ul>
</li>
<li><a class="reference internal" href="#formatting">Formatting</a><ul>
<li><a class="reference internal" href="#dates-and-times">Dates and times</a></li>
<li><a class="reference internal" href="#numbers">Numbers</a></li>
<li><a class="reference internal" href="#capitalization">Capitalization</a></li>
</ul>
</li>
<li><a class="reference internal" href="#writing-api-references">Writing API references</a><ul>
<li><a class="reference internal" href="#basics">Basics</a></li>
<li><a class="reference internal" href="#typography">Typography</a></li>
<li><a class="reference internal" href="#classes-structures-interfaces-enumerations">Classes, structures, interfaces, enumerations</a></li>
<li><a class="reference internal" href="#callable-symbols">Callable symbols</a></li>
<li><a class="reference internal" href="#properties">Properties</a></li>
<li><a class="reference internal" href="#code-examples">Code examples</a></li>
<li><a class="reference internal" href="#deprecations">Deprecations</a></li>
</ul>
</li>
<li><a class="reference internal" href="#what-s-new">What’s new</a></li>
<li><a class="reference internal" href="#related-resources">Related resources</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/furo.js"></script>
</body>
</html>