diff options
Diffstat (limited to 'files/uk/mdn/guidelines/writing_style_guide/index.html')
| -rw-r--r-- | files/uk/mdn/guidelines/writing_style_guide/index.html | 727 |
1 files changed, 727 insertions, 0 deletions
diff --git a/files/uk/mdn/guidelines/writing_style_guide/index.html b/files/uk/mdn/guidelines/writing_style_guide/index.html new file mode 100644 index 0000000000..f14340877a --- /dev/null +++ b/files/uk/mdn/guidelines/writing_style_guide/index.html @@ -0,0 +1,727 @@ +--- +title: Настанови зі стилю +slug: MDN/Guidelines/Writing_style_guide +tags: + - MDN Meta + - Style guide + - Настанови зі стилю + - Путівник +translation_of: MDN/Guidelines/Writing_style_guide +original_slug: MDN/Guidelines/Настанови_зі_стилю +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/uk/docs/MDN")}}</div> + +<p><span class="seoSummary">Щоб зробити викладення документації на MDN Web Docs однорідним, виразним та легкочитним, в цих настановах зазначено, як слід писати, форматувати й упорядковувати текст. Втім, це радше посібник, аніж перелік суворих вимог.</span> Звісно, нас більше цікавить вміст, аніж форма викладення, тож не переймайтесь надмірно докладним вивченням настанов зі стилю. Але й не дивуйтесь, якщо хтось із сумлінних добровольців згодом виправить ваш доробок задля дотримання наведених тут правил.</p> + +<p>Мовознавчі настанови цього посібника стосуються здебільшого англійської мови. Для інших мов можна й варто створювати окремі стильові посібники. Їх слід оприлюднювати як підстатті основної сторінки перекладацької команди.</p> + +<p>Стандарти стилю, що стосуються вмісту на інших (окрім MDN) сайтах, наведено у <a href="https://www.mozilla.org/en-US/styleguide/">Єдиному посібнику зі стилю Mozilla</a>.</p> + +<h2 id="Основи">Основи</h2> + +<p>Найкраще місце для початку в будь-якому великому керівництві - це певні базові текстові стандарти, які допомагають дотримуватись сумісності документації. Наступні розділи описуються деякі із цих основ, які допоможуть вам.</p> + +<h3 id="Назви_сторінок">Назви сторінок</h3> + +<p>Назви сторінок використовуються в результатах пошуку, а також для структурування ієрархії сторінок у списку "хлібних крихт" зверху сторінки. Назви сторінок (які відображаються зверху сторінки, а також у результатах пошуку) можуть відрізнятись від "slug" (унікальний ідентифікатор) соторінки, яка є частиною URL адреси після "<em><locale>/docs/</em>".</p> + +<h4 id="Регістр_заголовків_сторінок_та_розділів">Регістр заголовків сторінок та розділів</h4> + +<p>Заголовки сторінок та заголовки розділів мають починатись з великої літери (використовується лише для першого слова в реченні та власних імен), але не кожне слово:</p> + +<ul> + <li><span class="correct"><strong>Правильно</strong></span>: "Новий спосіб прокидувань в JavaScript"</li> + <li><span class="incorrect"><strong>Неправильно</strong></span>: "Новий Спосіб Прокидувань В JavaScript"</li> +</ul> + +<p>У нас є багато старих сторінок, які було написано до встановлення цього правила. За бажанням ви можете оновити їх, аби вони стали більш читабильними. Поступово ми доберемось до їх редагування.</p> + +<h4 id="Вибір_заголовків_та_коротких_заголовків.">Вибір заголовків та коротких заголовків.</h4> + +<p>Унікальний ідентифікатор має бути коротким; коли створюєте новий рівень ієрархії, компонент нового рівня у вигляді "slug" ідентифікатора має складатись із одного-двох слів.</p> + +<p>Заголовки сторінок, з іншої сторони, можуть бути такими довгими на скільки це потрібно і мають описувати суть статті.</p> + +<h4 id="Створення_нових_піддерев">Створення нових піддерев</h4> + +<p>Коли вам потрібно додати якісь статті до певної теми чи області обговорення, ви можете зробити це створивши цільову сторінку, після цього додавайте підсторінки для кожної окремої статті. Цільова сторінка має описуватись за допомогою одного або двох абзаців, які розкривають тему чи технологію, потім відобразіть список підсторінок з поясненням до кожної з них. Ви можете автоматизувати вставку сторінок в список, використовуючи макроси, які ми створили.</p> + +<p>For example, consider the <a href="/uk/docs/Web/JavaScript">JavaScript</a> guide, which is structured as follows:</p> + +<ul> + <li><a href="/uk/docs/Web/JavaScript/Guide" title="JavaScript/Guide">JavaScript/Guide</a> - Main table-of-contents page</li> + <li><a href="/uk/docs/Web/JavaScript/Guide/Introduction" title="JavaScript/Guide/JavaScript_Overview">JavaScript/Guide/JavaScript Overview</a></li> + <li><a href="/uk/docs/Web/JavaScript/Guide/Functions" title="JavaScript/Guide/Functions">JavaScript/Guide/Functions</a></li> + <li><a href="/uk/docs/Web/JavaScript/Guide/Dokladno_pro_Objectnu_Model" title="JavaScript/Guide/Details_of_the_Object_Model">JavaScript/Guide/Details of the Object Model</a></li> +</ul> + +<p>Try to avoid putting your article at the top of the hierarchy, which slows the site down and makes search and site navigation less effective.</p> + +<h3 id="General_article_content_guidelines">General article content guidelines</h3> + +<p>When writing any document, it's important to know how much to say. If you ramble on too long, the article becomes tedious to read and nobody will use it. Getting the amount of coverage right is important for several reasons. Among those reasons: to ensure that the reader finds the information they truly need, and to provide enough quality material for search engines to adequately analyze and rank the article. We'll discuss the former (providing the information the reader may need) here. To learn a little about ensuring that pages are properly classified and ranked by search engines, see the article <a href="/uk/docs/MDN/Contribute/Howto/Write_for_SEO">How to write for SEO on MDN</a>.</p> + +<p>The goal is to write pages that include all the information that readers may need without going on too long about it all. We have a few recommendations in this area.</p> + +<h4 id="Consider_your_audience">Consider your audience</h4> + +<p>Keep in mind that these are guidelines. Some of these tips may not apply in every case. Certainly keep your article's audience in mind. An article on advanced network techniques likely doesn't need to go into as much detail about basic networking concepts as the typical article on networking code, for instance.</p> + +<h4 id="Provide_a_useful_summary">Provide a useful summary</h4> + +<p>Make sure the article's summary—that is, the opening paragraph or paragraphs before the first heading—provides enough information for the reader to understand if the article is likely to be covering what they're interested in reading about. In guide or tutorial content, the summary should let the reader know what topics will be covered and what they're already expected to know, if anything. It should mention the technology, technologies, and/or APIs that are being documented or discussed, with links to those, and it should offer hints as to the situations in which the article's contents might be useful.</p> + +<h5 id="Example_Too_short!">Example: Too short!</h5> + +<p>This example of a summary is far too short. It leaves out too much information, such as what it means exactly to "stroke" text, where the text is drawn, and so forth.</p> + +<div class="example-bad"> +<p><strong><code>CanvasRenderingContext2D.strokeText()</code></strong> draws a string.</p> +</div> + +<h5 id="Example_Too_long!">Example: Too long!</h5> + +<p>Here, we've updated the summary, but now it's far too long. Too much detail is included, and the text gets far too much into other methods and properties. Instead, the summary should focus on the <code>strokeText()</code> method, and should refer to the appropriate guide where the other details are offered.</p> + +<div class="example-bad"> +<p>When called, the Canvas 2D API method <strong><code>CanvasRenderingContext2D.strokeText()</code></strong> strokes the characters in the specified string beginning at the coordinates specified, using the current pen color. In the terminology of computer graphics, "stroking" text means to draw the outlines of the glyphs in the string without filling in the contents of each character with color.</p> + +<p>The text is drawn using the context's current font as specified in the context's {{domxref("CanvasRenderingContext2D.font", "font")}} property.</p> + +<p>The placement of the text relative to the specified coordinates are determined by the context's <code>textAlign</code>, <code>textBaseline</code>, and <code>direction</code> properties. <code>textAlign</code> controls the placement of the string relative to the X coordinate specified; if the value is <code>"center"</code>, then the string is drawn starting at <code>x - (stringWidth / 2)</code>, placing the specified X-coordinate in the middle of the string. If the value is <code>"left"</code>, the string is drawn starting at the specified value of <code>x</code>. And if <code>textAlign</code> is <code>"right"</code>, the text is drawn such that it ends at the specified X-coordinate.</p> + +<p>(etc etc etc...)</p> + +<p>You can, optionally, provide a fourth parameter that lets you specify a maximum width for the string, in pixels. If you provide this parameter, the text is compressed horizontally or scaled (or otherwise adjusted) to fit inside a space that wide when being drawn.</p> + +<p>You can call the <strong><code>fillText()</code></strong> method to draw a string's characters as filled with color instead of only drawing the outlines of the characters.</p> +</div> + +<h5 id="Example_Much_better!">Example: Much better!</h5> + +<p>Here we see a much better overview for the <code>strokeText()</code> method.</p> + +<div class="example-good"> +<p>The {{domxref("CanvasRenderingContext2D")}} method <code><strong>strokeText()</strong></code>, part of the <a href="/uk/docs/Web/API/Canvas_API">Canvas 2D API</a>, strokes—that is, draws the outlines of—the characters of a specified string, anchored at the position indicated by the given X and Y coordinates. The text is drawn using the context's current {{domxref("CanvasRenderingContext2D.font", "font")}}, and is justified and aligned according to the {{domxref("CanvasRenderingContext2D.textAlign", "textAlign")}}, {{domxref("CanvasRenderingContext2D.textBaseline", "textBaseline")}}, and {{domxref("CanvasRenderingContext2D.direction", "direction")}} properties.</p> + +<p>For more details and further examples, see {{SectionOnPage("/uk/docs/Learn/JavaScript/Client-side_web_APIs/Drawing_graphics", "Text")}} in the Learning Area as well as our main article on the subject, <a href="/uk/docs/Web/API/Canvas_API/Tutorial/Drawing_text">Drawing text</a>.</p> +</div> + +<h4 id="Include_all_relevant_examples">Include all relevant examples</h4> + +<p>More pages should have examples than should not have them. The majority of pages most likely deserve multiple examples, in fact. It's important to ensure that you use examples to clarify what every parameter is used for, and to clarify any edge cases that may exist. You should also use examples to demonstrate solutions for common tasks, and you should use examples to demonstrate solutions to problems that may arise.</p> + +<p>Each example should be preceded by text explaining what the example does and anything the reader should know before beginning to read or try out the example.</p> + +<p>In addition, each piece of code should include an explanation of how it works. Keep in mind that it may make sense to break up a large piece of code into smaller portions so they can be described individually. The text following each piece of code should explain anything relevant, using an appropriate level of detail. If the code is very simple and doesn't really feature anything directly related to the API being documented, you may only give a quick summary of what it is and why it's there. If the code is intricate, uses the API being documented, or is technically creative, you should provide a more detailed explanation.</p> + +<p>When using the live sample system, it's helpful to be aware that all of the {{HTMLElement("pre")}} blocks in the area that contains the sample are concatenated together before running the example, which lets you break any or all of the HTML, CSS, and JavaScript into multiple segments, each optionally with its own descriptions, headings, and so forth. This makes documenting code incredibly powerful and flexible.</p> + +<h4 id="Overly-short_articles_are_hard_to_find">Overly-short articles are hard to find</h4> + +<p>If an article is "thin"—that is, too short—it may not be indexed properly (or at all) by search engines. As a rule of thumb, the article's body text should be at least 250-300 words. Don't artificially inflate a page that simply can't reasonably be made longer than that, but treat this guideline as a target to shoot for as a minimum when possible.</p> + +<h3 id="Sections_paragraphs_and_newlines">Sections, paragraphs, and newlines</h3> + +<p>Use heading levels in decreasing order: {{HTMLElement("h2")}} then {{HTMLElement("h3")}} then {{HTMLElement("h4")}}, without skipping levels. H2 is the highest level allowed because H1 is reserved for the page title. If you need more than three or four levels of headers you should consider breaking up the article into several smaller articles with a landing page, linking them together using the {{TemplateLink("Next")}}, {{TemplateLink("Previous")}}, and {{TemplateLink("PreviousNext")}} macros.</p> + +<p>The Enter (or Return) key on your keyboard starts a new paragraph. To insert a newline without a space, hold down the Shift key while pressing Enter.</p> + +<p>Don't create single subsections — you don't subdivide a topic into one. It's either two subheadings or more or none at all.</p> + +<p>Don't have bumping heads, which are headings followed immediately by headings. Aside from looking horrible, it's helpful to readers if every heading has at least a brief intro after it to introduce the subsections beneath.</p> + +<h3 id="Lists">Lists</h3> + +<p>Lists should be written in a similar format across all contributions. Correct procedures should include suitable punctuation and sentence structure regardless of the list format. However dependent on the type of list you are writing, you must adjust your format accordingly. Refer to the documentation below to understand the differences of each.</p> + +<h4 id="Bulleted_Lists">Bulleted Lists</h4> + +<p>Bulleted lists should be used for grouping purposes to create concise but effective pieces of information. Each new piece of information must start with a '•' to signify a new piece. Bulleted lists must follow standard punctuation usage, pay attention to the use of full stops; they must be included at the end of each sentence just like standard writing practice.</p> + +<p>An example of a correctly structured bulleted list:</p> + +<div class="example-good"> +<p><em>In this example we should include:</em></p> + +<ul> + <li><em>A condition, with a brief explanation.</em></li> + <li><em>A similar condition, with a brief explanation.</em></li> + <li> + <p><em>Yet another condition, some further explanation.</em></p> + </li> +</ul> +</div> + +<p>Note how the format remains the same from bullet to bullet. Create a bullet point, state a condition that has relevence to your indented topic and add some pausing punctuation in order to follow up the condition with a concise explanation.</p> + +<h4 id="Numbered_Lists">Numbered Lists</h4> + +<p>Instruction lists must follow suitable numbering and format. It is important to include these attributes as with instructions, being clear is a key priority. Create the list in a similar style to a bulleted list, however numbered or instruction lists can be extensive where necessary, meaning correct punctuation is vital as you will be forming complex sentences.</p> + +<p>An example of a correctly structured numbered list:</p> + +<blockquote> +<p><em>In order for you to structure a correct numbered list you must:</em></p> + +<p><em>1. Begin with creating an introductory heading to lead into the instructions. This way we can provide the user with context before beginning the instructions.</em></p> + +<p><em>2. Start creating your instructions, listing your instructions with numbers. This is a standard format of a numbered list that is easily recognizable by the user. Your instructions may be quite extensive, so it is important to write effectively and use correct punctuation where necessary.</em></p> + +<p><em>3. After you have finished your instructions, close off the numbered list with a brief explanation of the outcome upon completion.</em></p> + +<p><em>This is an example of writing your closing explanation. We have created a short numbered list which provides instructive steps to produce a numbered list with the correct formatting. </em></p> +</blockquote> + +<p>Numbered lists are almost exclusive for instructive purposes, so before writing consider your approach based on the context of the information you are trying to relay.</p> + +<h3 id="Text_formatting_and_styles">Text formatting and styles</h3> + +<p>Use the "Formatting Styles" drop-down list to apply predefined styles to selected content.</p> + +<div class="note">The "Note" style is used to call out important notes, like this one.</div> + +<div class="warning">Similarly, the "Warning" style creates warning boxes like this.</div> + +<p>Unless specifically instructed to do so, <strong>do not</strong> use the HTML <code>style</code> attribute to manually style content. If you can't do it using a predefined class, drop into {{IRCLink("mdn")}} and ask for help.</p> + +<h3 id="Code_sample_style_and_formatting">Code sample style and formatting</h3> + +<div class="note"> +<p><strong>Note</strong>: This section deals with the styling/formatting of code as it appears on an MDN article. If you want guidelines on actually writing code examples, see our <a href="/uk/docs/MDN/Contribute/Guidelines/Code_samples">Code sample guidelines</a>.</p> +</div> + +<h4 id="Tabs_and_line_breaks">Tabs and line breaks</h4> + +<p>Use two spaces per tab in all code examples. Indent the code cleanly, with open-brace ("{") characters on the same line as the statement that opens the block. For example:</p> + +<pre class="brush: js notranslate">if (condition) { + /* handle the condition */ +} else { + /* handle the "else" case */ +} +</pre> + +<p>Long lines shouldn't be allowed to stretch off horizontally to the extent that they require horizontal scrolling to read. Instead, break at natural breaking points. Some examples follow:</p> + +<pre class="brush: js notranslate">if (class.CONDITION || class.OTHER_CONDITION || class.SOME_OTHER_CONDITION + || class.YET_ANOTHER_CONDITION ) { + /* something */ +} + +var toolkitProfileService = Components.classes["@mozilla.org/toolkit/profile-service;1"] + .createInstance(Components.interfaces.nsIToolkitProfileService); +</pre> + +<h4 id="Inline_code_formatting">Inline code formatting</h4> + +<p>Use the "Code" button (labeled with two angle brackets "<>") to apply inline code-style formatting to function names, variable names, and method names (this uses the {{HTMLElement("code")}} element). For example, "the <code class="js plain">frenchText()</code> function".</p> + +<p>Method names should be followed by a pair of parentheses: <code>doSomethingUseful()</code>. The parentheses help differentiate methods from other code terms.</p> + +<h4 id="Syntax_highlighting">Syntax highlighting</h4> + +<p><img alt="Screenshot of the 'Syntax Highlighter' menu." src="https://mdn.mozillademos.org/files/12682/Language%20list.png" style="border-style: solid; border-width: 1px; float: right; margin: 2px 4px;">Entire lines (or multiple lines) of code should be formatted using syntax highlighting rather than the {{HTMLElement("code")}} element. Select the appropriate language from the language list button (the one with the two code blocks), as seen in the screenshot to the right. This will insert a preformatted code box with line numbers and syntax highlighting for the chosen language.</p> + +<p>The following example shows text with JavaScript formatting:</p> + +<div class="line number2 index1 alt1"> +<pre class="brush: js notranslate">for (var i = 0, j = 9; i <= 9; i++, j--) + document.writeln("a[" + i + "][" + j + "]= " + a[i][j]);</pre> +</div> + +<p>If no appropriate language is available, use ("No Highlight" in the language menu). This will result in code without syntax highlighting:</p> + +<pre class="brush: plain notranslate">x = 42;</pre> + +<h4 id="Syntax_definitions">Syntax definitions</h4> + +<p>If you want to insert a syntax definition, you can choose the "Syntax Box" option from the "Styles" drop-down menu in the editor toolbar. This will give the syntax definition a special formatting distinguishing it from normal code.</p> + +<h4 id="Blocks_not_referring_to_code">Blocks not referring to code</h4> + +<p>There are a few use cases where a <pre> block does not refer to code and doesn't have syntax highlighting nor line numbers. In such cases you should add a <pre> without class. Those cases include things like tree structures:</p> + +<pre class="notranslate">root/ + + folder1/ + file1 + + folder2/ + file2 + file3 +</pre> + +<p>To create preformatted content without syntax highlighting and line numbers click the "pre" button in the toolbar. Then start to type the text.</p> + +<h4 id="Styling_HTML_element_references">Styling HTML element references</h4> + +<p>There are specific rules to follow when writing about HTML elements. These rules produce consistent descriptions of elements and their components. They also ensure correct linking to detailed documentation.</p> + +<dl> + <dt>Element names</dt> + <dd>Use the {{TemplateLink("HTMLElement")}} macro, which creates a link to the page for that element. For example, writing \{{HTMLElement("title")}} produces "{{HTMLElement("title")}}". If you don't want to create a link, <strong>enclose the name in angle brackets</strong> and use "Code (inline)" style (e.g., <code><title></code>).</dd> + <dt>Attribute names</dt> + <dd>Use <strong>bold face</strong>.</dd> + <dt>Attribute definitions</dt> + <dd>Use the {{TemplateLink("htmlattrdef")}} macro (e.g., <span class="nowiki">\{{htmlattrdef("type")}}</span>) for the definition term, so that it can be linked to from other pages, then use the {{TemplateLink("htmlattrxref")}} macro (e.g., <span class="nowiki">\{{htmlattrxref("attr","element")}}</span>) to reference attribute definitions.</dd> + <dt>Attribute values</dt> + <dd>Use "Code (inline)" style, and do not use quotation marks around strings, unless needed by the syntax of a code sample. For example: When the <strong>type</strong> attribute of an <code><input></code> element is set to <code>email</code> or <code>tel</code> ...</dd> + <dt>Labeling attributes</dt> + <dd>Use labels like {{HTMLVersionInline(5)}} thoughtfully. For example, use them next to the bold attribute name but not for every occurrence in your body text.</dd> +</dl> + +<h3 id="Latin_abbreviations">Latin abbreviations</h3> + +<h4 id="In_notes_and_parentheses">In notes and parentheses</h4> + +<ul> + <li>Common Latin abbreviations (etc., i.e., e.g.) may be used in parenthetical expressions and notes. Use periods in these abbreviations, followed by a comma or other appropriate punctuation. + <ul> + <li><span class="correct"><strong>Correct</strong></span>: Web browsers (e.g., Firefox) can be used ...</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: Web browsers e.g. Firefox can be used ...</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: Web browsers, e.g. Firefox, can be used ...</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: Web browsers, (eg: Firefox) can be used ...</li> + </ul> + </li> +</ul> + +<h4 id="In_running_text">In running text</h4> + +<ul> + <li>In regular text (i.e., text outside of notes or parentheses), use the English equivalent of the abbreviation. + <ul> + <li><span class="correct"><strong>Correct</strong></span>: ... web browsers, and so on.</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: ... web browsers, etc.</li> + <li><span class="correct"><strong>Correct</strong></span>: Web browsers such as Firefox can be used ...</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: Web browsers e.g. Firefox can be used ...</li> + </ul> + </li> +</ul> + +<h4 id="Meanings_and_English_equivalents_of_Latin_abbreviations">Meanings and English equivalents of Latin abbreviations</h4> + +<table class="fullwidth-table"> + <tbody> + <tr> + <th>Abbrev</th> + <th>Latin</th> + <th>English</th> + </tr> + <tr> + <td>cf.</td> + <td><em>confer</em></td> + <td>compare</td> + </tr> + <tr> + <td>e.g.</td> + <td><em>exempli gratia</em></td> + <td>for example</td> + </tr> + <tr> + <td>et al.</td> + <td><em>et alii</em></td> + <td>and others</td> + </tr> + <tr> + <td>etc.</td> + <td><em>et cetera</em></td> + <td>and so forth, and so on</td> + </tr> + <tr> + <td>i.e.</td> + <td><em>id est</em></td> + <td>that is, in other words</td> + </tr> + <tr> + <td>N.B.</td> + <td><em>nota bene</em></td> + <td>note well</td> + </tr> + <tr> + <td>P.S.</td> + <td><em>post scriptum</em></td> + <td>postscript</td> + </tr> + </tbody> +</table> + +<div class="note"> +<p>Always consider whether it's truly beneficial to use a Latin abbreviation. Some of these are used so rarely that many readers won't understand the meaning, and others are often confused with one another. And be sure that <strong>you</strong> use them correctly, if you choose to do so. For example, be careful not to confuse "e.g." with "i.e.", which is a common error.</p> +</div> + +<h3 id="Acronyms_and_abbreviations">Acronyms and abbreviations</h3> + +<h4 id="Capitalization_and_periods">Capitalization and periods</h4> + +<p>Use full capitals and delete periods in all acronyms and abbreviations, including organizations such as "US" and "UN".</p> + +<ul> + <li><span class="correct"><strong>Correct</strong></span>: XUL</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: X.U.L.; Xul</li> +</ul> + +<h4 id="Expansion">Expansion</h4> + +<p>On the first mention of a term on a page, expand acronyms likely to be unfamiliar to users. When in doubt, expand it, or, better, link it to the article or <a href="/uk/docs/Glossary">glossary</a> entry describing the technology.</p> + +<ul> + <li><span class="correct"><strong>Correct</strong></span>: "XUL (XML User Interface Language) is Mozilla's XML-based language..."</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: "XUL is Mozilla's XML-based language..."</li> +</ul> + +<h4 id="Plurals_of_acronyms_and_abbreviations">Plurals of acronyms and abbreviations</h4> + +<p>For plurals of acronyms or abbreviations, add <em>s</em>. Don't use an apostrophe. Ever. Please.</p> + +<ul> + <li><span class="correct"><strong>Correct</strong></span>: CD-ROMs</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: CD-ROM's</li> +</ul> + +<h4 id="Versus_vs._and_v.">"Versus", "vs.", and "v."</h4> + +<p>The contraction "vs." is preferred.</p> + +<ul> + <li><span class="correct"><strong>Correct</strong></span>: this vs. that</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: this v. that</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: this versus that</li> +</ul> + +<h3 id="Capitalization">Capitalization</h3> + +<p>Use standard English capitalization rules in body text, and capitalize "World Wide Web." It is acceptable to use lower case for "web" (used alone or as a modifier) and "internet;" this guideline is a change from a previous version of this guide, so you may find many instances of "Web" and "Internet" on MDN. Feel free to change these as you are making other changes, but editing an article just to change capitalization is not necessary.</p> + +<p>Keyboard keys should use sentence-style capitalization, not all-caps capitalization. For example, "Enter" not "ENTER."</p> + +<h3 id="Contractions">Contractions</h3> + +<p>Our writing style tends to be casual, so you should feel free to use contractions (e.g., "don't", "can't", "shouldn't") if you prefer.</p> + +<h3 id="Pluralization">Pluralization</h3> + +<p>Use English-style plurals, not the Latin- or Greek-influenced forms.</p> + +<ul> + <li><span class="correct"><strong>Correct</strong></span>: syllabuses, octopuses</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: syllabi, octopi</li> +</ul> + +<h3 id="Hyphenation">Hyphenation</h3> + +<p>Hyphenate compounds when the last letter of the prefix is a vowel and is the same as the first letter of the root.</p> + +<ul> + <li><font color="green"><strong>Correct</strong></font>: email, re-elect, co-op</li> + <li><font color="red"><strong>Incorrect</strong></font>: e-mail, reelect, coop</li> +</ul> + +<h3 id="Gender-neutral_language">Gender-neutral language</h3> + +<p>It is a good idea to use gender-neutral language in any writing where gender is irrelevant to the subject matter, to make the text as inclusive as possible. So for example, if you are talking about the actions of a specific man, usage of he/his would be fine, but if the subject is a person of either gender, he/his isn't appropriate.<br> + <br> + Let's take the following example:</p> + +<blockquote> +<p>A confirmation dialog appears, asking the user if he allows the Web page to make use of his Web cam.</p> +</blockquote> + +<blockquote> +<p>A confirmation dialog appears, asking the user if she allows the Web page to make use of her Web cam.</p> +</blockquote> + +<p>Both versions are gender-specific. To fix this, use gender-neutral pronouns:</p> + +<blockquote> +<p>A confirmation dialog appears, asking the user if they allow the Web page to make use of their Web cam.</p> +</blockquote> + +<div class="note"> +<p>MDN allows the use of this very common syntax (which is controversial among usage authorities), to make up for the lack of a neutral gender in English. The use of the third-person plural as a gender neutral pronoun (that is, using "they," "them", "their," and "theirs") is an accepted practice, commonly known as "<a href="https://en.wikipedia.org/wiki/Singular_they">singular 'they.'</a>"</p> +</div> + +<p>You can use both genders:</p> + +<blockquote> +<p>A confirmation dialog appears, asking the user if he or she allows the web page to make use of his/her web cam.</p> +</blockquote> + +<p>making the users plural:</p> + +<blockquote> +<p>A confirmation dialog appears, asking the users if they allow the web page to make use of their web cams.</p> +</blockquote> + +<p>The best solution, of course, is to rewrite and eliminate the pronouns:</p> + +<blockquote> +<p>A confirmation dialog appears, requesting the user's permission for web cam access.</p> +</blockquote> + +<blockquote> +<p>A confirmation dialog box appears, which asks the user for permission to use the web cam.</p> +</blockquote> + +<p>The last way of dealing with the problem is arguably better, as it is not only grammatically more correct but removes some of the complexity associated with dealing with genders across different languages that may have wildly varying gender rules. This solution can make translation easier for both readers and localizers.</p> + +<h3 id="Numbers_and_numerals">Numbers and numerals</h3> + +<h4 id="Dates">Dates</h4> + +<p>For dates (not including dates in code samples) use the format "January 1, 1990".</p> + +<ul> + <li><span class="correct"><strong>Correct</strong></span>: February 24, 2006</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: February 24th, 2006; 24 February, 2006; 24/02/2006</li> +</ul> + +<p>Alternately, you can use the YYYY/MM/DD format.</p> + +<ul> + <li><span class="correct"><strong>Correct</strong></span>: 2006/02/24</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: 02/24/2006; 24/02/2006; 02/24/06</li> +</ul> + +<h4 id="Decades">Decades</h4> + +<p>For decades, use the format "1990s". Don't use an apostrophe.</p> + +<ul> + <li><span class="correct"><strong>Correct</strong></span>: 1990s</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: 1990's</li> +</ul> + +<h4 id="Plurals_of_numerals">Plurals of numerals</h4> + +<p>For plurals of numerals add "s". Don't use an apostrophe.</p> + +<ul> + <li><span class="correct"><strong>Correct</strong></span>: 486s</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: 486's</li> +</ul> + +<h4 id="Commas">Commas</h4> + +<p>In running text, use commas only in five-digit and larger numbers.</p> + +<ul> + <li><span class="correct"><strong>Correct</strong></span>: 4000; 54,000</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: 4,000; 54000</li> +</ul> + +<h3 id="Punctuation">Punctuation</h3> + +<h4 id="Serial_comma">Serial comma</h4> + +<p><strong>Use the serial comma</strong>. The serial (also known as "Oxford") comma is the comma that appears before the conjunction in a series of three or more items.</p> + +<ul> + <li><span class="correct"><strong>Correct</strong></span>: I will travel on trains, planes, and automobiles.</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: I will travel on trains, planes and automobiles.</li> +</ul> + +<div class="note"> +<p>This is in contrast to the <a href="https://www.mozilla.org/en-US/styleguide/" title="https://mozilla-l10n.github.io/styleguides/uk/">One Mozilla style guide</a>, which specifies that the serial comma is not to be used. MDN is an exception to this rule.</p> +</div> + +<h3 id="Spelling">Spelling</h3> + +<p>For words with variant spellings, always use their American English spelling. In general, use the first entry at <a href="http://www.dictionary.com/">Dictionary.com</a>, unless that entry is listed as a variant spelling or as being primarily used in a non-American form of English; for example, if you <a href="http://dictionary.reference.com/browse/honour">look up "honour"</a>, you find the phrase "Chiefly British" followed by a link to the American standard form, "<a href="http://dictionary.reference.com/browse/honor">honor</a>". Do not use variant spellings.</p> + +<ul> + <li><span class="correct"><strong>Correct</strong></span>: localize, honor</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: localise, honour</li> +</ul> + +<h3 id="Terminology">Terminology</h3> + +<dl> +</dl> + +<h4 id="HTML_elements">HTML elements</h4> + +<p>Use "elements" to refer to HTML and XML elements, rather than "tags". In addition, they should almost always be wrapped in "<>", and should be in the {{HTMLElement("code")}} style. When you reference a given element for the first time in a section, you should use the {{TemplateLink("HTMLElement")}} macro to create a link to the documentation for the element (unless you're writing within that element's reference document page).</p> + +<ul> + <li><span class="correct"><strong>Correct</strong></span>: the {{HTMLElement("span")}} element</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: the span tag</li> +</ul> + +<h4 id="Parameters_vs._arguments">Parameters vs. arguments</h4> + +<p>The preferred term on MDN is <strong>parameters</strong>. Please avoid the term "arguments" for consistency if at all possible.</p> + +<h4 id="User_interface_actions">User interface actions</h4> + +<p>In task sequences, describe user interface actions using the imperative mood. Identify the user interface element by its label and type.</p> + +<ul> + <li><span class="correct"><strong>Correct</strong></span>: Click the Edit button.</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: Click Edit.</li> +</ul> + +<h3 id="Voice">Voice</h3> + +<p>While the active voice is preferred, the passive voice is also acceptable, given the informal feel of our content. Try to be consistent, though.</p> + +<h2 id="Wiki_markup_and_usage">Wiki markup and usage</h2> + +<h3 id="Links">Links</h3> + +<p>Links are a large part of what makes a wiki a powerful learning and teaching tool. Below you'll find some basic information, but you can find a complete guide to <a href="/uk/docs/MDN/Contribute/Editor/Links">creating and editing links on MDN</a> in our editor guide.</p> + +<p>We encourage you to create appropriate links among articles; they help improve navigation and discoverability of content. You can easily create links not only among pages on MDN (internal links) but also to pages outside MDN (external links).</p> + +<p>There are two ways to create links: you explicitly create a link using the Link button in the editor's toolbar—or by pressing <kbd>Ctrl</kbd>+<kbd>K</kbd> (<kbd>Cmd</kbd>-<kbd>K</kbd> on the Mac)—or you can use MDN's powerful macro system to generate links automatically or based on an input value.</p> + +<p>When deciding what text to use as a link, there are a few guidelines you can follow:</p> + +<ul> + <li>Whenever a macro exists which will create the link you need, and you are able to do so, please do. <a href="/uk/docs/MDN/Contribute/Editor/Links#Using_link_macros">Using macros to create links</a> will not only help you get it right, but will allow future improvements to MDN to automatically be applied to your link.</li> + <li>For an API name, use the entire string of the API term as written in your content. The easiest way to do this is to <a href="/uk/docs/MDN/Contribute/Editor/Links#Linking_to_documentation_for_APIs">use the appropriate macro</a> to construct a properly-formatted link for you.</li> + <li>For a term for which you're linking to a page defining or discussing that term, use the name of the term and no additional text as the link's text. For example: + <ul> + <li><span class="correct"><strong>Correct</strong></span>: You can use <a href="/uk/docs/Web/JavaScript">JavaScript</a> code to create dynamic applications on the Web.</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: You can use <a href="/uk/docs/Web/JavaScript">JavaScript code</a> to create dynamic applications on the Web.</li> + </ul> + </li> + <li>Otherwise, when adding a useful link to prose, try to choose an action and object phrase, such as: + <ul> + <li><span class="correct"><strong>Correct</strong></span>: If you'd like to <a href="/uk/docs/Mozilla/Developer_guide">contribute to the Firefox project</a>, your first step is to <a href="/uk/docs/Mozilla/Developer_guide/Build_Instructions">download and build Firefox</a>.</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: <a href="/uk/docs/Mozilla/Developer_guide">If you'd like to contribute to the Firefox project</a>, your first step is to <a href="/uk/docs/Mozilla/Developer_guide/Build_Instructions">download and build</a> Firefox.</li> + </ul> + </li> +</ul> + +<h4 id="URL_schemes">URL schemes</h4> + +<p>For security reasons, you should only create links that use the following schemes:</p> + +<ul> + <li><code>http://</code></li> + <li><code>https://</code></li> + <li><code>ftp://</code></li> + <li><code>mailto:</code></li> +</ul> + +<p>Others may or may not work, but are not supported and will probably be removed by editorial staff.</p> + +<div class="note"> +<p>In particular, be sure not to use the <code>about:</code> or <code>chrome://</code> schemes, as they will not work. Similarly, the <code>javascript:</code> scheme is blocked by most modern browsers, as is <code>jar:</code>.</p> +</div> + +<h3 id="Page_tags">Page tags</h3> + +<p>Tags provide meta information about a page and/or indicate that a page has specific improvements needed to its content. Every page in the wiki should have tags. You can find details on tagging in our <a href="/uk/docs/MDN/Contribute/Howto/Tag">How to properly tag pages</a> guide.</p> + +<p>The tagging interface lives at the bottom of a page while you're in edit mode, and looks something like this:</p> + +<p><img alt="Screenshot of the UX for adding and removing tags on MDN" src="https://mdn.mozillademos.org/files/7859/tag-interface.png" style="border-style: solid; border-width: 1px; height: 167px; width: 863px;"></p> + +<p>To add a tag, click in the edit box at the end of the tag list and type the tag name you wish to add. Tags will autocomplete as you type. Press enter (or return) to submit the new tag. Each article may have as many tags as needed. For example, an article about using JavaScript in AJAX programming might have both "JavaScript" and "AJAX" as tags.</p> + +<p>To remove a tag, just click the little "X" icon in the tag.</p> + +<h4 id="Tagging_pages_that_need_work">Tagging pages that need work</h4> + +<p>In addition to using tags to track information about the documentation's quality and content, we also use them to mark articles as needing specific types of work.</p> + +<h4 id="Tagging_obsolete_pages">Tagging obsolete pages</h4> + +<p>Use the following tags for pages that are not current:</p> + +<ul> + <li><em>Junk</em>: Use for spam, pages created by mistake, or content that is so bad that it should be deleted. Pages with this tag are deleted from time to time.</li> + <li><em>Obsolete</em>: Use for content that is technically superseded, but still valid in context. For example an HTML element that is obsolete in HTML5 is still valid in HTML 4.01. You can also use the <span class="nowiki">{{TemplateLink("obsolete_header")}}</span> macro to put a prominent banner on the topic.</li> + <li><em>Archive</em>: Use for content that is technically superseded and no longer useful. If possible, add a note to the topic referring readers to a more current topic. For example, a page that describes how to use the Mozilla CVS repository should refer readers to a current topic on using Mercurial repos. (If no corresponding current topic exists, use the <em>NeedsUpdate</em> tag, and add an explanation on the Talk page.) Pages with the Archive tag are eventually moved from the main content of MDN to the <a href="/uk/docs/Archive">Archive</a> section.</li> +</ul> + +<h3 id="SEO_summary">SEO summary</h3> + +<p>The SEO summary provides a short description of a page. It will be reported as a summary of the article to robots crawling the site, and will then appear in search results for the page. It is also used by macros that automate the construction of landing pages inside MDN itself.</p> + +<p>By default, the first paragraph of the page is used as the SEO summary. However, you can override this behavior by marking a section with the <a href="/uk/docs/MDN/Contribute/Editor/Basics">"SEO summary" style in the WYSIWYG editor</a>.</p> + +<h3 id="Landing_pages">Landing pages</h3> + +<p><strong>Landing pages</strong> are pages at the root of a topic area of the site, such as the main <a href="/uk/docs/Web/CSS" title="CSS">CSS</a> or <a href="/uk/docs/Web/HTML" title="HTML">HTML</a> pages. They have a standard format that consists of three areas:</p> + +<ol> + <li>A brief (typically one paragraph) overview of what the technology is and how it's used. See {{anch("Writing a landing page overview")}} for tips.</li> + <li>A two-column list of links with appropriate headings. See {{anch("Creating a page link list")}} for guidelines.</li> + <li>An <strong>optional</strong> "Browser compatibility" section at the bottom of the page.</li> +</ol> + +<h4 id="Creating_a_page_link_list">Creating a page link list</h4> + +<p>The link list section of an MDN landing page consists of two columns. These are created using the following HTML:</p> + +<pre class="brush: html notranslate"><div class="row topicpage-table"> + <div class="section"> + ... left column contents ... + </div> + <div class="section"> + ... right column contents ... + </div> +</div></pre> + +<p>The left column should be a list of articles, with an <code><h2></code> header at the top of the left column explaining that it's a list of articles about the topic (e.g., "Documentation and tutorials about foo"); this header should use the CSS class "Documentation". Below that is a <code><dl></code> list of articles with each article's link in a <code><dt></code> block and a brief one-or-two sentence summary of the article in the corresponding <code><dd></code> block.</p> + +<p>The right column should contain one or more of the following sections, in order:</p> + +<dl> + <dt>Getting help from the community</dt> + <dd>This should provide information on Matrix chat rooms and mailing lists available on the topic. The heading should use the class "Community".</dd> + <dt>Tools</dt> + <dd>A list of tools the user can look at to help with the use of the technology described in this section of MDN. The heading should use the class "Tools".</dd> + <dt>Related topics</dt> + <dd>A list of links to landing pages for other, related, technologies of relevance. The heading should use the class "Related_Topics".</dd> +</dl> + +<p><strong><<<finish this once we finalize the landing page standards>>></strong></p> + +<h2 id="Using_inserting_images">Using, inserting images</h2> + +<p>It's sometimes helpful to provide an image in an article you create or modify, especially if the article is very technical. To include an image:</p> + +<ol> + <li>Attach the desired image file to the article (at the bottom of every article in edit mode)</li> + <li>Create an image in the WYSIWYG editor</li> + <li>In the WYSIWYG editor, in the drop-down list of attachments, select the newly created attachment that is your image</li> + <li>Press OK.</li> +</ol> + +<h2 id="Other_references">Other references</h2> + +<h3 id="Preferred_style_guides">Preferred style guides</h3> + +<p>If you have questions about usage and style not covered here, we recommend referring to the <a href="http://www.economist.com/styleguide/introduction">Economist style guide</a> or, failing that, the <a href="https://www.amazon.com/Chicago-Manual-Style-16th/dp/0226104206">Chicago Manual of Style</a>.</p> + +<h3 id="Preferred_dictionary">Preferred dictionary</h3> + +<p>For questions of spelling, please refer to <a href="http://www.dictionary.com/">Dictionary.com</a>. The spelling checker for this site uses American English. Please do not use variant spellings (e.g., use <em>color</em> rather than <em>colour</em>).</p> + +<p>We will be expanding the guide over time, so if you have specific questions that aren't covered in this document, please send them to the <a href="/uk/docs/MDN/Community">MDC mailing list</a> or <a href="/uk/docs/User:Sheppy" title="User:Sheppy">project lead</a> so we know what should be added.</p> + +<h3 id="MDN-specific">MDN-specific</h3> + +<ul> + <li><a href="/uk/docs/MDN/Contribute/Structures/Шаблони/Загальновживані_шаблони">Commonly-used macros</a> on MDN, with explanations.</li> +</ul> + +<h3 id="Лексика_граматика_й_правопис">Лексика, граматика й правопис</h3> + +<p>If you're interested in improving your writing and editing skills, you may find the following resources to be helpful.</p> + +<ul> + <li><a href="http://www.amazon.com/Writing-Well-30th-Anniversary-Nonfiction/dp/0060891548">On Writing Well</a>, by William Zinsser (Amazon link)</li> + <li><a href="http://www.amazon.com/Style-Basics-Clarity-Grace-4th/dp/0205830765/" title="http://www.amazon.com/Style-Lessons-Clarity-Grace-Edition/dp/0321898680">Style: The Basics of Clarity and Grace</a>, by Joseph Williams and Gregory Colomb (Amazon link)</li> + <li><a href="https://brians.wsu.edu/common-errors-in-english-usage/">Common Errors in English</a></li> + <li><a href="http://www-personal.umich.edu/~jlawler/aue.html">English Grammar FAQ</a> (alt.usage.english)</li> + <li><a href="http://www.angryflower.com/bobsqu.gif">Bob's quick guide to the apostrophe, you idiots</a> (funny)</li> + <li><a href="http://www.amazon.com/Merriam-Websters-Concise-Dictionary-English-Usage/dp/B004L2KNI2" title="http://www.amazon.com/Merriam-Websters-Concise-Dictionary-English-Usage/dp/B004L2KNI2">Merriam-Webster's Concise Dictionary of English Usage</a> (Amazon link): Scholarly but user-friendly, evidence-based advice; very good for non-native speakers, especially for preposition usage.</li> + <li><a href="http://english.stackexchange.com/">English Language and Usage StackExchange</a>: Question and answer site for English language usage.</li> +</ul> |