diff --git a/docs/src/attributes.inc.adoc b/docs/src/attributes.inc.adoc new file mode 100644 index 00000000000..78aa061faa7 --- /dev/null +++ b/docs/src/attributes.inc.adoc @@ -0,0 +1,31 @@ +:lversion: {sys: cat ../VERSION} +:lbranch: {sys: git rev-parse --abbrev-ref HEAD} + +:date: {sys: LANG=C date --date="@$(dpkg-parsechangelog --file ../debian/changelog -S timestamp)" '+%d %b %Y'} +:revdate: {docdate} +:builddate: {localdate} + +:experimental: +:masterdir: {indir} +:doctype: book +:ascii-ids: +:toc: +:lang: en + +// Custom lang highlight +// must come after the doc title, to work around a bug in asciidoc 8.6.6 +:ini: {basebackend@docbook:'':ini} +:hal: {basebackend@docbook:'':hal} +:ngc: {basebackend@docbook:'':ngc} +:css: {basebackend@docbook:'':css} + +:wlo-url: https://www.linuxcnc.org +:wlo: {wlo-url}[LinuxCNC website] +:ldocs-url: {wlo-url}/documents +:ldocs: {ldocs-url}[LinuxCNC documentation] +:ldocs-base-html: {docs-base}/{branch}/{lang}/html/ +:ldocs-base-pdf: {docs-base}/{branch}/{lang}/pdf/ +:lrepo-url: https://github.com/LinuxCNC/linuxcnc.git +:lrepo: {lrepo-url}[LinuxCNC repository] +:lbbot-url: http://buildbot.linuxcnc.org/ +:lbbot: {lbbot-url}[LinuxCNC Builbot] diff --git a/docs/src/code/docs-style-guide.adoc b/docs/src/code/docs-style-guide.adoc new file mode 100644 index 00000000000..d90923753c5 --- /dev/null +++ b/docs/src/code/docs-style-guide.adoc @@ -0,0 +1,1882 @@ +include::../attributes.inc.adoc[] +:description: Writing styles, markup, formatting, and other standards for LinuxCNC Documentation. +//:group: unassigned +//:info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +//:stage: none + +[[docs:style-guide]] += Documentation Style Guide + +// Preamble Start +This document defines the standards for LinuxCNC documentation, including +grammar, formatting, word use, and more. + +//// +FIXME Communication channels for docs style guide and with docs team in general +TODO Automatic labelling of issues and PRs +For style questions, mention `@docs-style` in an issue or pull request. +If you have access to one of the LinuxCNC chat platforms, use the +`#linuxcnc-docs` channel. +//// + +//// +TODO Other docs +In addition to this page, the following resources can help you craft and +contribute to documentation: + +* xref:../index.adoc[Doc contribution guidelines] +* xref:word_list.adoc[Recommended word list] +* xref:../testing.adoc[Doc style and consistency testing] +* https://design.gitlab.com/content/error-messages/[UI text guidelines] +* https://about.gitlab.com/handbook/communication/#writing-style-guidelines[LinuxCNC Handbook style guidelines] +* https://docs.microsoft.com/en-us/style-guide/welcome/[Microsoft Style Guide] +* https://developers.google.com/style[Google Developer Documentation Style Guide] +* https://gitlab.com/dashboard/merge_requests?scope=all&state=merged&label_name[]=tw-style¬[label_name][]=docs%3A%3Afix[Recent updates to this guide] +//// +// Preamble End + +[[docs:style:ssot]] +== Single Source Of Truth (SSOT) + +The {ldocs} is the SSOT for all information related to LinuxCNC implementation, +usage, and troubleshooting. + +It evolves continuously, in keeping with new features, and with improvements +for clarity, accuracy, and completeness. + +This policy prevents information silos, making it easier to find information +about LinuxCNC applications. + +It also informs decisions about the kinds of content we include in our +documentation. + +=== Include all information + +Include problem-solving actions that may address rare cases or be considered +risky, but provide proper context through fully detailed warnings and +caveats. + +This kind of content should be included as it could be helpful to others +and, when properly explained, its benefits outweigh the risks. If you +think you have found an exception to this rule, contact the +Technical Writing team. + +LinuxCNC adds all troubleshooting information to the documentation, no +matter how unlikely a user is to encounter a situation. + +//// +FIXME Add Troubleshooting documentation +LinuxCNC Support maintains their own +link:../../../administration/index.md#support-team-documentation[troubleshooting content] +in the LinuxCNC documentation. +//// + +[[docs:style:media]] +=== Include all media types + +Include any media types/sources if the content is relevant to readers. + +You can freely include or link presentations, diagrams, and videos. No +matter who it was originally composed for, if it is helpful to any of +our audiences, we can include it. + +* If you use an image that has a separate source file (for example, a + vector or diagram format), link the image to the source file so that + anyone can update or reuse it. +* Do not copy and paste content from other sources unless it is a limited + quotation with the source cited. Typically it is better to either rephrase + relevant information in your own words or link out to the other source. + +//// +=== Documentation structure + +TODO Revise documentation structure + @silopolis: Structure documentation in parts targeted at user personas: + * Administrator + * Integrator + * User + * Contributor + +FIXME Sync Web and PDF documentation structure +//// + +//// +TODO Define LinuxCNC topic types +=== Topic types + +In the software industry, it is a best practice to organize documentation +in different types: + +* Concepts / Explanations (Understanding-oriented) +* Tasks / Tutorials (Learning-oriented) +* Reference (Information-oriented) +* Troubleshooting / How-to guides (Problem-oriented) + +See: + +* https://documentation.divio.com/ +* https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/development/documentation/topic_types + +Ideally, every significant matter should be present in the target part(s) +of the documentation and should offer content in each relevant topic. + +LinuxCNC has not traditionally used topic types. However, we are starting +to move in this direction, so we can address these issues: + +* *Content is hard to find.* + + Our docs are comprehensive and include a large amount of useful information. + Topic types create repeatable patterns that make our content easier to + scan and parse. +* *Content is often written from the contributor's point of view.* + + Our docs are written by contributors. Topic types (tasks specifically) + help put information into a format that is geared toward helping others, + rather than documenting how a feature was implemented. + +LinuxCNC uses these xref:../structure.adoc[topic types]. +//// + +=== Link instead of repeating text + +Rather than repeating information from another topic, link to the single +source of truth and explain why it is important. + +//// +FIXME Could we adopt a documentation first methodology ? +=== Docs-first methodology + +We employ a documentation-first methodology. This method ensures the +documentation remains a complete and trusted resource, and makes +communicating about the use of LinuxCNC more efficient. + +* If the answer to a question exists in documentation, share the link to + the documentation instead of rephrasing the information. +* When you encounter new information not available in LinuxCNC documentation + (for example, when solving an issue, helping another user, or testing + a feature), your first step should be to + https://github.com/LinuxCNC/linuxcnc/issues[create a pull request (PR)] + to add this information to the documentation. You can then share the PR + to communicate this information. + +New information that would be useful toward the future usage or troubleshooting +of LinuxCNC should not be written directly in a forum or other messaging +system, but added to a documentation PR and then referenced, as described +above. + +The more we reflexively add information to the documentation, the more +the documentation helps others efficiently accomplish tasks and solve problems. + +If you have questions when considering, authoring, or editing documentation, +ask the Technical Writing team. They're available in `#linuxcnc-docs` rooms +on messaging platforms or in +https://forum.linuxcnc.org/32-documents[LinuxCNC forum Documents category]. +// FIXME Do we need/want assignments ? +//by mentioning https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments[the writer for] +// FIXME Do we need/want a more formal workflow ? +//the applicable https://about.gitlab.com/handbook/product/categories/#devops-stages[DevOps stage or group]. +Otherwise, forge ahead with your best effort. It does not need to be perfect; +the team is happy to review and improve upon your content. Review the +// TODO Development development front page +xref:index.adoc[Documentation guidelines] before you begin your first +documentation PR. + +Maintaining a knowledge base separate from the documentation would be against +the documentation-first methodology, because the content would overlap with +the documentation. +//// + +[[docs:style:asciidoc]] +== AsciiDoc + +All LinuxCNC documentation is written using +https://en.wikipedia.org/wiki/AsciiDoc[AsciiDoc]. + +=== HTML in AsciiDoc + +Hard-coded HTML is valid, although it's discouraged from being used. + +HTML is permitted if: + +* There's no equivalent markup in AsciiDoc. +* Advanced tables are necessary. +* Special styling is required. +* Reviewed and approved by a technical writer. + +=== Headings in AsciiDoc + +Each documentation page begins with a level 1 heading (`=`). + +This becomes the `h1` element when the page is rendered to HTML. + +There can be only *one* level 1 heading per page. + +* For each subsection, increment the heading level. + In other words, increment the number of `=` characters in front of the + heading. +* Avoid headings greater than `H5` (`=====`). If you need more than five + heading levels, move the topics to a new page instead. + +// Headings greater than `H5` do not display in the right sidebar navigation. +* Do not skip a level. For example: `==` > `====`. +* Leave one blank line before and after the heading. + +// FIXME Title anchoring +When you change heading text, the anchor link changes. + +To avoid broken links: + +* Do not use step numbers in headings. +* When possible, do not use words that might change in the future. + +Also, do not use links as part of heading text. + +// TODO See also xref:../structure.adoc[heading guidelines for specific topic types]. + +=== Backticks in AsciiDoc + +Use backticks for things that are either typed into the system or read in +the system: + +* Commands, options, parameters names. +* Packages, modules, classes, functions, arguments names. +* <>. +* Error messages. + +//// +TODO Documentation testing and AsciiDoc linting +IDEA Use po4a as linter ? Pre-commit hook ? + +=== AsciiDoc Rules + +LinuxCNC ensures that the AsciiDoc used across all documentation is consistent, as +well as easy to review and maintain, by xref:../testing.adoc[testing documentation changes] +with link:../testing.md#markdownlint[markdownlint]. This lint test fails when any +document has an issue with AsciiDoc formatting that may cause the page to render +incorrectly in LinuxCNC. It also fails when a document has +non-standard AsciiDoc (which may render correctly, but is not the current +standard for LinuxCNC documentation). + +==== AsciiDoc rule `MD044/proper-names` (capitalization) + +A rule that could cause confusion is `MD044/proper-names`, as it might not be +immediately clear what caused markdownlint to fail, or how to correct the +failure. This rule checks a list of known words, listed in the `.markdownlint.yml` +file in each project, to verify proper use of capitalization and backticks. +Words in backticks are ignored by markdownlint. + +In general, product names should follow the exact capitalization of the official +names of the products, protocols, and so on. + +Some examples fail if incorrect capitalization is used: + +* MinIO (needs capital `IO`) +* NGINX (needs all capitals) +* runit (needs lowercase `r`) + +Additionally, commands, parameters, values, filenames, and so on must be +included in backticks. For example: + +* "Change the `needs` keyword in your `.gitlab-ci.yml`..." + ** `needs` is a parameter, and `.gitlab-ci.yml` is a file, so both need backticks. +Additionally, `.gitlab-ci.yml` without backticks fails markdownlint because it +does not have capital G or L. +* "Run `git clone` to clone a Git repository..." + ** `git clone` is a command, so it must be lowercase, while Git is the product, +so it must have a capital G. +//// + +[[docs:style:language]] +== Language + +LinuxCNC documentation should be clear and easy to understand. + +* Avoid unnecessary words. +* Be clear, concise, and stick to the goal of the topic. +* Write in US English with US grammar. + +//// +TODO grammar and spell checking + https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml[`British.yml`] + https://vale.sh/ + https://github.com/errata-ai/vale-action + https://github.com/errata-ai/packages +//// + +=== Capitalization + +As a project, we tend toward lowercase. + +==== Headings + +//// +FIXME Choose titles capitalization style: sentence or headline +https://github.com/nofluffjuststuff/nfjsmag-docs/blob/master/author-writing-style-and-syntax-guide.adoc#headline +//// + +Use sentence case. For example: + +* `= Use variables to configure pipelines` +* `== Use the To-Do List` + +==== User interfaces text + +When referring to specific user interface (UI) text, like a button label +or menu item, use the same capitalization that's displayed in the user +interface. + +//// +TODO Standards for this content are listed in the +https://design.gitlab.com/content/punctuation/[Pajamas Design System Content section] +and typically match what's mentioned in this Documentation Style Guide. +//// + +If you think the UI text contains style mistakes, create an issue or a PR +to propose a change to the user interface text. + +==== Feature names + +* Feature names are typically lowercase. +* Some features require title case, typically nouns that name LinuxCNC-specific + capabilities or tools. + + Features requiring title case should be added to the + xref:word_list.adoc[word list]. +//// +FIXME No equivalent linter to markdownlint to use a config file like + https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.yml + so that it can be consistently applied across all documentation. +//// + +If the term is not in the word list, ask a LinuxCNC Technical Writer for +advice. + +==== Other terms + +Capitalize names of: + +* Third-party organizations, software, and products. For example, FreeCAD, + MachineKit, Git, and The Linux Foundation. +* Methods or methodologies. For example, Continuous Integration, + Continuous Deployment, Unit Testing, and Agile. + +Follow the capitalization style listed at the authoritative source for the +entity, which may use non-standard case styles. For example: LinuxCNC and +npm. + +[[docs:style:fake]] +=== Fake data + +==== Fake user informations + +Do not use real user informations or email addresses in LinuxCNC documentation. +For email addresses and names, use: + +* Email addresses: Use an email address ending in `example.com`. +* Names: Use strings like `example_username`. Alternatively, use diverse + or non-gendered names with common surnames, such as `Sidney Jones`, + `Zhang Wei`, or `Alex Garcia`. + +==== Fake URLs + +When including sample URLs in the documentation, use `example.com` when +the domain name is generic. + +=== Contractions + +Contractions are encouraged to make writing simpler and easier to read. +They can create a friendly and informal tone, especially in tutorials, +instructional documentation, and user interfaces. + +However, don’t make a sentence harder to understand just to follow this +rule. + +|=== +| Do | Don’t + +| it’s, can’t, wouldn’t, you’re, you’ve, haven’t, don’t +| it is, cannot, would not, it’ll, should’ve +|=== + +Some contractions, however, should be avoided: + +// vale gitlab.Possessive = NO + +|=== +| Do not use a contraction | Example | Use instead + +| With a proper noun and a verb +| The *Container Registry's* a powerful feature. +| The *Container Registry* is a powerful feature. + +| To emphasize a negative +| *Don't* install X with Y. +| *Do not* install X with Y. + +| In reference documentation +| *Don't* set a limit. +| *Do not* set a limit. + +| In error messages +| Requests to localhost *aren't* allowed. +| Requests to localhost *are not* allowed. +|=== + +// vale gitlab.Possessive = YES + +=== Acronyms + +If you use an acronym, spell it out on first use on a page. + +You do not need to spell it out more than once on a page. + +When possible, try to avoid acronyms in headings. + +=== Numbers + +When using numbers in text: + +* spell out zero through nine +* use numbers for 10 and greater + +For details, see the https://docs.microsoft.com/en-us/style-guide/numbers[Microsoft Style Guide]. + +== Text + +* Write in <>. +// FIXME Decide on fixed line width. +// @silopolis: 100 seems to correspond more or less to the number of +// characters in a line on a printed page +* Splitting long lines (preferably up to 100 characters) can make it easier + to provide feedback on small chunks of text. +* Insert an empty line for new paragraphs. +* Insert an empty line between different markups (for example, after every + paragraph, header, list, and so on). Example: ++ +```markdown +== Header + +Paragraph. + +* List item 1 +* List item 2 +``` + +* Use forced line breaks `+` to structure paragraphs and create clarity. + +=== Comments + +// FIXME Comments + +To embed comments within AsciiDoc, use standard HTML comments that are not +rendered when published. + +Example: + +`+html + ++` + +=== Emphasis + +Use _italic_ to provide _emphasis_ or when you are introducing a term for +the first time. + +Use *bold* to provide *strong emphasis*. + +//// +FIXME Could we switch to sans-serif fonts, please ?! +LinuxCNC uses a sans-serif font and italic text does not stand out as much +as it would in a serif font. + +For details, see https://practicaltypography.com/bold-or-italic.html[Butterick's Practical Typography guide on bold or italic]. +//// + +* Use asterisks (`\*`) to mark a word or text in bold (`*bold*`). +* Use underscore (`\_`) for text in italics (`_italic_`). +* Use backticks (```) for blockquotes. + +=== Punctuation + +Follow these guidelines for punctuation: + +// vale gitlab.Repetition = NO + +* End full sentences with a period. +* Use one space between sentences. +* Do not use semicolons. Use two sentences instead. +* Do not use double spaces. +// TODO Test with https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SentenceSpacing.yml[`SentenceSpacing.yml`]. +* Do not use non-breaking spaces. Use standard spaces instead. +// TODO Test with https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/lint-doc.sh[`lint-doc.sh`]. +* Do not use tabs for indentation. Use spaces instead. + + You can configure your code editor to output spaces instead of tabs + when pressing the tab key. +* Use serial (Oxford) commas before the final *and* or *or* in a list of + three or more items. +// TODO Test with https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OxfordComma.yml[`OxfordComma.yml`]. +* Avoid dashes. Use separate sentences, or commas, instead. +* Do not use typographer's ("curly") quotes. Use straight quotes instead. +// TODO Test with https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/NonStandardQuotes.yml[`NonStandardQuotes.yml`]. + +// vale gitlab.Repetition = YES + +=== Placeholder text + +// TODO Extend with complete usage message syntax + +You might want to provide a command or configuration that uses specific +values. + +In these cases, use https://en.wikipedia.org/wiki/Usage_message#Pattern[`<` and `>`] +to call out where a reader must replace text with their own value. + +For example: + +[source,sh] +cp + +=== Keyboard commands + +Use the keyboard macro with the `+kbd:[key(+key)*]+` syntax when referring +to keystroke presses. + +Multiple keys are separated by a plus, and alpha keys should be represented +in uppercase. + +For example: + +[source] +To stop the command, press kbd:[Control+C]. + +When the docs are generated, the output is: + +==== +To stop the command, press kbd:[Control+C]. +==== + +// TODO Add escaped characters https://docs.asciidoctor.org/asciidoc/latest/macros/keyboard-macro/ + +=== Text entered in the UI + +If you want the user to type something in the UI, use backticks. + +For example: + +[source] +In the *Commit message* box, type `This is my merge request`. + +Backticks are more precise than quotes and avoid painful escaping when input +text contains quotes. + +=== Inline code + +Inline code style is applied inline with regular text. + +Use inline code style: + +* For filenames or fragments of configuration files. + + For example: `.gitlab-ci.yml`, `CODEOWNERS`, and `only: [main]`. +* For methods and STATUS messages + For example: FIXME + +To apply inline code style, wrap the text in a single backtick (```). + +For example: `this is inline code style`. + +=== Code blocks + +Code block style separates code text from regular text. + +Use code block style for commands run in the command-line interface. + +Code block style is easier to copy and paste in a user's terminal window. + +// FIXME Code blocks styling +// https://docs.asciidoctor.org/asciidoc/latest/verbatim/source-blocks/ +// https://asciidoc-py.github.io/userguide.html#X104 +To apply code block style, wrap the text in quadruple dashes (four `-`) +and add a `source` style with the adequate language. +For example: + + +---- +This is codeblock style +---- + +When using code block style: + +* Use quadruple backticks (four ```) to apply code block style when the + code block you are styling has triple backticks in it. + + For example, when illustrating code block style. +* Add a blank line above and below code blocks. +* Syntax highlight hints are required for code blocks. + + See the https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers[list of supported languages and lexers] + for available syntax highlighters. + + Use `plaintext` if no better hint is available. + +== Lists + +* Always start list items with a capital letter, unless they're parameters + or commands that are in backticks, or similar. +* Always leave a blank line before and after a list. +* Begin a line with spaces (not tabs) to denote a <>. + +// TODO Complex lists https://docs.asciidoctor.org/asciidoc/latest/lists/continuation/ + +=== Choose between an ordered or unordered list + +Use ordered lists for a sequence of steps, ie: + +[source,adoc] +---- +Follow these steps to do something. + +. First, do the first step. +. Then, do the next step. +. Finally, do the last step. +---- + +Use an unordered lists when the steps do not need to be completed in order, +ie: + +[source,adoc] +---- +These things are imported: + +* Thing 1 +* Thing 2 +* Thing 3 +---- + +=== Markup + +* Use asterisk (`*`) for unordered lists. +* Use dots/periods (`.`) for ordered lists. + +// TODO Forcing lists appart +// https://docs.asciidoctor.org/asciidoc/latest/lists/unordered/ +// https://docs.asciidoctor.org/asciidoc/latest/lists/separating/ + +=== Punctuation + +* Don't add commas (`,`) or semicolons (`;`) to the ends of list items. +* If a list item is a complete sentence (with a subject and a verb), add + a period at the end. +* Majority rules: if the majority of items do not end in a period, do not + end any of the items in a period. +* Separate list items from explanatory text with a colon (`:`). + + For example: ++ +[source,adoc] +---- +The list is as follows: + +* First item: this explains the first item. +* Second item: this explains the second item. +---- + +=== Nesting inside a list item + +// TODO Nesting lists https://docs.asciidoctor.org/asciidoc/latest/lists/unordered/ + +It's possible to nest items under a list item, so that they render with +the same indentation as the list item. This can be done with: + +// FIXME Anchors +* <> +* <> +* <> +* <> + +Items nested in lists should always align with the first character of the +list item. In unordered lists (using `*`), this means two spaces for each +level of indentation: + +[source,adoc] +---- +- Unordered list item 1 + + A line nested using 2 spaces to align with the `U` above. + +* Unordered list item 2 ++ +____ +A quote block that will nest +inside list item 2. +____ + +* Unordered list item 3 ++ +----- +a code block that nests inside list item 3 +----- + +* Unordered list item 4 ++ +image:image.png[an image that will nest inside list item 4] +---- + +For explicitly numbered ordered lists, use three spaces for each level of +indentation: + +[source,adoc] +---- +1. Ordered list item 1 + +A line nested using 3 spaces to align with the `O` above. + +. Ordered list item 2 ++ +____ +A quote block that will nest +inside list item 2. +____ + +. Ordered list item 3 ++ +----- +a code block that nests inside list item 3 +----- + +. Ordered list item 4 ++ +image:image.png[an image that will nest inside list item 4] +---- + +You can nest full lists inside other lists using the same rules as above. +If you want to mix types, that's also possible, if you don't mix items at +the same level: + +[source,adoc] +---- +1. Ordered list item one. +1. Ordered list item two. + - Nested unordered list item one. + - Nested unordered list item two. +1. Ordered list item three. + +* Unordered list item one. +* Unordered list item two. + .. Nested ordered list item one. + .. Nested ordered list item two. +* Unordered list item three. +---- + +[[docs:style:tables]] +== Tables + +Tables should be used to describe complex information in a straightforward +manner. Note that in many cases, an unordered list is sufficient to describe +a list of items with a single, simple description per item. But, if you +have data that's best described by a matrix, tables are the best choice. + +// TODO Improve tables +// https://docs.asciidoctor.org/asciidoc/latest/tables/build-a-basic-table/ +// https://asciidoc-py.github.io/userguide.html#_tables + +=== Creation guidelines + +To keep tables accessible and scannable, tables should not have any +empty cells. If there is no otherwise meaningful value for a cell, consider entering +*N/A* for 'not applicable' or *None*. + +To help tables be easier to maintain, consider adding additional spaces to the +column widths to make them consistent. + +For example: + +[source,adoc] +---- +|=== +| App name | Description | Requirements + +| App 1 | Description text 1. | Requirements 1 +| App 2 | Description text 2. | None +|=== +---- + +// TODO Editors plugins or extensions for formatting AsciiDoc tables ? + +=== Table headings + +Use sentence case for table headings. + +For example: `Keyword value` or `Project name`. + +=== Feature tables + +// FIXME Feature tables, or delete ? +When creating tables of lists of features use these phrases: + +|=== +| Option | AsciiDoc | Displayed result + +| No +| `+**{dotted-circle}** No+` +| *\{dotted-circle}* No + +| Yes +| `+**{check-circle}** Yes+` +| *\{check-circle}* Yes +|=== + + +[[docs:style:footnotes]] +== Footnotes + +For tables footnotes, use: + +* A superscript number between square brackets at the end of cell content, + separated by a space. +* An ordered list below the table for footnotes content + +For example: + +[source,adoc] +---- +|=== +| App name | Description | + +| App A | Description text. ^[1]^ +| App B | Description text. ^[2]^ +|=== + +. This is the first footnote. +. This is the second footnote. +---- + +This text renders this output: + +|=== +| App name | Description + +| App A | Description text. ^[1]^ +| App B | Description text. ^[2]^ +|=== + +. This is the first footnote. +. This is the second footnote. + + +[[docs:style:quotes]] +== Quotes + +* Standard quotes: double quotes (`"`). + + Example: "This is wrapped in double quotes". +* Quote inside a quote: double quotes (`"`) wrapped into single quotes (`'`). + + Example: "This sentence 'quotes' something in a quote". + +//// +TODO Other punctuation rules, refer to the + https://design.gitlab.com/content/punctuation/[Pajamas Design System Punctuation section]. + This is overridden by the <>. +//// + + +[[docs:style:links]] +== Links + +// https://asciidoc-py.github.io/userguide.html#_inline_macros + +Links are important in LinuxCNC documentation. Use links instead of +summarizing to help preserve a <>. + +We include guidance for links in these categories: + +* How to set up <> for headings. +* How to set up <> for configuring a link. +//// +TODO Applications embedded help ? +* What to set up when link:../../documentation/index.md#linking-to-help[linking to a `help`] +page. +//// +* How to set up <> + for cross-references. +* How to set up <> + for authoritative sources. +// * When to use <>. +* How to set up a <>. +* How to <> + +[[docs:style:anchors]] +=== Anchor links + +Headings generate anchor links when rendered: `== This is an example` generates +the anchor `#this-is-an-example`. + +Keep in mind that: + +* LinuxCNC user interfaces can link to documentation pages and anchor links + to take the user to the right spot. +* Crosslinking is encouraged into documentation as part of the SSOT policy. + +Thus, when you change a heading, search `docs/*` for the old anchor and +fix the possible broken links. + +If you do not fix these links, the link:../checkref[`checkref` script] +will choke and documentation build will fail. + +Important: + +* Avoid crosslinking documentation to headings unless you need to link to + a specific section of the document. This avoids breaking anchors in the + future in case the heading is changed. +* If possible, avoid changing headings, because they're not only linked + internally. There are various links to LinuxCNC documentation on the + internet, such as tutorials, presentations, forum posts, and other sources. +* Do not link to `h1` headings. + +=== Basic link criteria + +* Use inline URL macro `+https://example.com[Text]+`. +* Use meaningful anchor text. + + For example, instead of writing something like `Read more about merge + requests [here]`, write `Read more about [merge requests]`. +* Put the entire link on a single line. + + Some tools do not work with links split over multiple lines, and incorrect + or broken links could slip through and cause problems downstream. + +=== Links to internal documentation + +// TODO Anchor links `[[...]]` creation policy and pattern +// https://docs.asciidoctor.org/asciidoc/latest/macros/xref/ + +NOTE: *Internal* refers to documentation in the same repository. + + When linking to documentation in separate projects (for example, linking + to MesaCT or QtPyVCP), you must use absolute URLs. + +Do not use absolute URLs like +`+https://linuxcnc.org/docs/stable/html/getting-started/about-linuxcnc.html[]+` +to cross-link to other documentation in the same project. + +Use relative links to the file like `+link:../getting-started/about-linuxcnc.adoc[]+`, +these are converted to HTML when the site is rendered. + +Relative linking enables cross-links to work: + +* In editors, review apps, and local previews. +* When working on the documentation locally, so you can verify that they + work as early as possible in the process. +//// +TODO apps embedded help +* In the LinuxCNC user interfaces when browsing doc files in their respective + repositories. For example, the links displayed at + `+https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md+`. +//// + +To link to internal documentation: + +* Use relative links to AsciiDoc files in the same repository. +* Do not use absolute URLs or URLs from `https://linuxcnc.org/docs/`. +* Use `../` to navigate to higher-level directories. +* Don't prepend `./` to links to files or directories. + + To link to a file in the same directory or one of its sub-directories, + use the syntax `path/to/file.adoc`. +* Don't link relative to root. For example, `/getting-started/about-linuxcnc.adoc`. +* Always add the filename `file.adoc` at the end of the link with the + `.adoc` extension, not `.html`. ++ +Don't: + + ** `../../merge_requests/` + ** `../../issues/tags.html` + ** `../../issues/tags.html#stages` + ++ +Do: + + ** `../../merge_requests/index.md` + ** `../../issues/tags.md` + ** `../../issues/tags.md#stages` + ** `issues/tags.md` + +=== Links to external documentation + +When possible, avoid links to external documentation. These links can easily +become outdated, and are difficult to maintain. + +* https://en.wikipedia.org/wiki/Link_rot[They lead to link rot]. +* They create issues with maintenance. + +Sometimes links are required. They might clarify troubleshooting steps or +help prevent duplication of content. + +Sometimes they are more precise and will be maintained more actively. + +For each external link you add, weigh the user benefit with the maintenance +difficulties. + +//// +=== Links requiring permissions + +Don't link directly to: + +* xref:../../../user/project/issues/confidential_issues.adoc[Confidential issues]. +* Project features that require xref:../../../user/permissions.adoc[special permissions] +to view. + +These fail for: + +* Those without sufficient permissions. +* Automated link checkers. + +Instead: + +* To reduce confusion, mention in the text that the information is either: + ** Contained in a confidential issue. + ** Requires special permission to a project to view. +* Provide a link in back ticks (```) so that those with access to the issue +can navigate to it. + +Example: + +`+markdown +For more information, see the [confidential issue](../../../user/project/issues/confidential_issues.md) `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/`. ++` +//// + +=== Link to specific lines of code + +When linking to specific lines in a file, link to a commit instead of to +the branch. Lines of code change over time. Linking to a line by using +the commit link ensures the user lands on the line you're referring to. +The *Permalink* button, displayed when viewing a file in a project, +provides a link to the most recent commit of that file. + +* Do: `+https://github.com/LinuxCNC/linuxcnc/blob/e11daeb96779ebdeb7a811e2034b40dabbd45cbb/docs/src/getting-started/about-linuxcnc.adoc?plain=1#L3[link to line 3].+` +* Don't: `+https://github.com/LinuxCNC/linuxcnc/blob/master/docs/src/getting-started/about-linuxcnc.adoc?plain=1#L3[link to line 3]+` + +If that linked expression has changed line numbers due to additional +commits, you can still search the file for that query. In this case, update +the document to ensure it links to the most recent version of the file. + + +[[docs:style:navigation]] +== Navigation + +When documenting how to navigate through the LinuxCNC UIs: + +* Always use location, then action. + ** From the *File* menu (location), select *Open...* (action). +* Be brief and specific. + + For example: + ** Do: Select *Save*. + ** Do not: Select *Save* for the changes to take effect. +* If a step must include a reason, start the step with it. + + This helps the user scan more quickly. + ** Do: To view the changes, in the merge request, select the link. + ** Do not: Select the link in the merge request to view the changes. +* Use ordered lists to describe sequences of operations. + +//// +TODO === Names for menus + +Use these terms when referring to the main LinuxCNC user interface +elements: + +FIXME UIs bars: Menu bar, Tool bar, Status bar, other(s) ? +* *Top bar*: This is the top bar that spans the width of the user interface. + It includes the menu, the LinuxCNC logo, search field, counters, and the user's avatar. +* *Left sidebar*: This is the navigation sidebar on the left of the user + interface, specific to the project or group. +* *Right sidebar*: This is the navigation sidebar on the right of the user + interface, specific to the open issue, merge request, or epic. +//// + +=== Names for UI elements + +// TODO https://docs.asciidoctor.org/asciidoc/latest/macros/ui-macros/ +UI elements, like button and checkbox names, should be *`monotype bold`*. + +[source,adoc] +---- +Click the *`Open`* button. +---- + +Which will render as: + +Click the *`Open`* button. + +// TODO Guidance for each individual UI element is in link:word_list.adoc[the word list] + +=== How to write navigation task steps + +Explicit full menu navigation paths using right pointing chevron ("greater +than") surrounded by white spaces ` > ` to separate each menu level or entry. + +Navigation paths should be in *`monotype bold`*. + +Example: + +[source,adoc] +---- +. In the menu bar, select *`File > Open...`* and find your NC program file. +. Select program file and click the *`Open`* button. +---- + +Which will render as: + +. In the menu bar, select *`File > Open...`* and find your NC program file. +. Select program file and click the *`Open`* button. + +//// +TODO Navigation tasks templates +To be consistent, use these templates when you write navigation steps in +a task topic. + +To open project settings: + +---- +. On the top bar, select **Main menu > Projects** and find your project. +. On the left sidebar, select **Settings > CI/CD**. +. Expand **General pipelines**. +---- + +To open group settings: + +---- +. On the top bar, select **Main menu > Groups** and find your group. +. On the left sidebar, select **Settings > CI/CD**. +. Expand **General pipelines**. +---- + +To open the Admin Area: + +---- +. On the top bar, select **Main menu > Admin**. +---- + +To select your avatar: + +---- +. On the top bar, in the top right corner, select your avatar. +---- + +To save the selection in some dropdown lists: + +---- +. Go to your issue. +. On the right sidebar, in the **Iteration** section, select **Edit**. +. From the dropdown list, select the iteration to associate this issue with. +. Select any area outside the dropdown list. +---- +//// + +=== Optional steps + +If a step is optional, start the step with the word `Optional` followed +by a period. + +For example: + +---- +. Optional. Enter a description for the job. +---- + +=== Recommended steps + +If a step is recommended, start the step with the word `Recommended` followed +by a period. + +For example: + +---- +. Recommended. Enter a description for the job. +---- + +=== Documenting multiple fields at once + +If the UI text sufficiently explains the fields in a section, do not include +a task step for every field. + +Instead, summarize multiple fields in a single task step. + +Use the phrase *Complete the fields*. + +// TODO Replace by an actual LinuxCNC example, like in Axis +For example: + +. On the top bar, select menu:Main menu[Projects] and find your project. +. On the left sidebar, select menu:Settings[Repository]. +. Expand *Push rules*. +. Complete the fields. + +If you are documenting multiple fields and only one field needs explanation, +do it in the same step with a forced line break: + +. Expand *Push rules*. +. Complete the fields. + + *Branch name* must be a regular expression. + +To describe multiple fields, use unordered list items: + +. Expand *General pipelines*. +. Complete the fields. + ** *Branch name* must be a regular expression. + ** *User* must be a user with at least the *Maintainer* role. + + +[[docs:style:images]] +== Images + +Images, including screenshots, can help a reader better understand a concept. +However, they should be used sparingly because: + +* They tend to become out-of-date. +* They are difficult and expensive to localize. +* They cannot be read by screen readers. + +When needed, use images to help the reader understand: + +* Where they are in a complicated process. +* How they should interact with the application. + +[[docs:style:captures]] +=== Screen captures + +When you take screenshots: + +* *Ensure it provides value.* + + Don't use `lorem ipsum` text. + + Try to replicate how the feature would be used in a real-world scenario, + and <>. +* *Capture only the relevant UI.* + + Don't include unnecessary white space or areas of the UI that don't help + illustrate the point. + + Some parts of the UIs can change, so don't include them in screenshots + unless absolutely necessary. +* *Keep it small.* + + If you don't need to show the full width of the screen, don't. + + Reduce the size of the application window as much as possible to keep + elements close together and reduce empty space. + + Try to keep the screenshot dimensions as small as possible. +* *Review how the image renders on the page.* + + Preview the image locally or use the preview on GitHub once pushed. + + Make sure the image isn't blurry or overwhelming. +* *Be consistent.* + + Coordinate screenshots with the other screenshots already on a documentation + page for a consistent reading experience. + + Ensure you use the default preferences for appearance and UI themes. + +=== Add callouts + +If you need to emphasize an area in a screenshot, use an arrow. + +* For color, use `#EE2604`. +* For the line width, use 3 pt. +* Use the simple triangular plain arrow style. +* If you have multiple arrows, make them parallel when possible. + +=== Save the image + +* Resize any wide or tall screenshots if needed, but make sure the screenshot + is still clear after being resized and compressed. +* All images *must* be <> to 100KB or less.+ + In many cases, 25-50KB or less is often possible without reducing image + quality. +* Save the image with a lowercase filename that's descriptive of the feature + or concept in the image: + ** If the image is of an application interface append the LinuxCNC version + to the filename based on this format: `image_name_vX_Y.png`. + + If the application version differs for LinuxCNC's, use the former one. + For example, for a screenshot taken from the Axis UI of LinuxCNC 2.8.4, + a valid name is `axis_v2_8_4.png`. + ** If you're adding an illustration that doesn't include parts of the + user interface, add the release number corresponding to the release + the image was added to. + + For a PR added to future 2.9.0 version, a valid name for an illustration + is `components_diagram_v2_9_0.png`. +* Place images in a separate directory named `img/` in the same directory + where the `.adoc` document that you're working on is located. +* Consider using PNG images instead of JPEG. +// TODO Propose FOSS alternative solutions to compress GIFs +* Images should be used (only when necessary) to illustrate the description + of a process, not to replace it. +* See also how to link and embed <> to illustrate + the documentation. + +=== Insert the image into content + +// TODO Expand block image insertion infos +// https://asciidoc-py.github.io/userguide.html#_block_macros +// https://docs.asciidoctor.org/asciidoc/latest/macros/images/ +The AsciiDoc code for including an image in a document is: + +---- +`image::img/document_image_title_vX_Y.png["Image description which will be the alt tag"]` +---- + +The image description is the alt text for the rendered image on the +documentation site. + +For accessibility and SEO, use https://webaim.org/techniques/alttext/[descriptions] +that: + +* Are accurate, succinct, and unique. +* Don't use *image of* or *graphic of* to describe the image. + +// TODO Add inline image insertion infos +// https://asciidoc-py.github.io/userguide.html#_inline_macros + +[[docs:style:compress]] +=== Compress images + +You should always compress any new images you add to the documentation. + +One known tool is https://pngquant.org/[`pngquant`], which is cross-platform +and open source. Install it by visiting the official website and/or following +the instructions for your OS. + +//// +TODO Use GitLab's or provide our images compression helper script + +If you use macOS and want all screenshots to be compressed automatically, read +https://about.gitlab.com/blog/2020/01/30/simple-trick-for-smaller-screenshots/[One simple trick to make your screenshots 80% smaller]. + +GitLab has a https://gitlab.com/gitlab-org/gitlab/-/blob/master/bin/pngquant[Ruby script] +that you can use to simplify the manual process. In the root directory of +your local copy of `+https://gitlab.com/gitlab-org/gitlab+`, run in a terminal: + +* Before compressing, if you want, check that all documentation PNG images have +been compressed: ++ +---- +bin/pngquant lint +---- + +* Compress all documentation PNG images using `pngquant`: ++ +---- +bin/pngquant compress +---- + +* Compress specific files: ++ +---- +bin/pngquant compress doc/user/img/award_emoji_select.png doc/user/img/markdown_logo.png +` + +* Compress all PNG files in a specific directory: ++ +---- +bin/pngquant compress doc/user/img +---- +//// + +Compress GIFs with https://ezgif.com/optimize or similar tool. + +=== Animated images + +Avoid using animated images (such as animated GIFs). They can be distracting +and annoying for users, and they will be fixed in printed form. + +If you're describing a complicated interaction in the user interface and +want to include a visual representation to help readers understand it, you +can: + +* Use a static image (screenshot) and if necessary, add callouts to emphasize + an area of the screen. +* Create a short video of the interaction and link to it. + +//// +TODO Emojis +== Emojis + +Don't use the AsciiDoc emoji format, for example `:smile:`, for any purpose. Use +<> instead. + +Use of emoji in AsciiDoc requires LinuxCNC Flavored AsciiDoc, which is not supported by Kramdown, +the AsciiDoc rendering engine used for LinuxCNC documentation. +//// + +[[docs:style:icons]] +== Icons + +//// +TODO LinuxCNC Icons +____ +https://gitlab.com/gitlab-org/gitlab-docs/-/issues/384[Introduced] in GitLab 12.7. +____ + +You can use icons from the https://gitlab-org.gitlab.io/gitlab-svgs/[GitLab SVG library] +directly in the documentation. For example, `+**{tanuki}**+` renders as: *\{tanuki}*. + +TODO Icons substitution attributes like {edit} or {trash} +//// + +In most cases, you should avoid using the icons in text. + +However, you can use an icon when hover text is the only available way to +describe a UI element. + +For example, *Delete* or *Edit* buttons often have hover text only. + +When you do use an icon, start with the hover text and follow it with the +inline icon: + +* Avoid: `+Select image:pencil.svg[] *Edit*.+` + + This generates as: Select image:pencil.svg[] *Edit*. +* Use instead: `+Select *Edit* (image:pencil.svg[]).+` + + This generates as: Select *Edit* (image:pencil.svg[]). + +Do not use words to describe the icon: + +* Avoid: `+Select *Erase job log* (the trash icon).+` +* Use instead: `+Select *Erase job log* (image:remove.svg[]).+` + + This generates as: Select *Erase job log* (image:remove.svg[]). + +[[docs:style:videos]] +== Videos + +Adding LinuxCNC YouTube video tutorials to the documentation is highly +encouraged, unless the video is outdated. Videos should not replace +documentation, but complement or illustrate it. If content in a video is +fundamental to a feature and its key use cases, but isn't adequately +covered in the documentation, you should: + +* Add this detail to the documentation text. +* Create an issue to review the video and update the page. + +Do not upload videos to the product repositories. <> or +<> them instead. + +=== Link to video + +To link out to a video, include a YouTube icon so that readers can scan +the page for videos before reading: + +`markdown + +For an overview, see [Video Title](link-to-video). +` + +You can link any up-to-date video that's useful to the LinuxCNC user. + +//// +TODO Embed videos + https://asciidoc-py.github.io/userguide.html#X98 + https://docs.asciidoctor.org/asciidoc/latest/macros/audio-and-video/ +=== Embed videos + +____ +https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/472[Introduced] in Gitlab 12.1. +____ + +The https://docs.gitlab.com[LinuxCNC documentation site] supports embedded +videos. + +You can embed videos from https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg[the official YouTube account for LinuxCNC] only. +For videos from other sources, <> them instead. + +In most cases, <>, because embedded videos +take up a lot of space on the page and can be distracting to readers. + +To embed a video: + +. Copy the code from this procedure and paste it into your AsciiDoc file. + + Leave a blank line above and below it. + + Do not edit the code (don't remove or add any spaces). + +. In YouTube, visit the video URL you want to display. + + Copy the regular URL from your browser + (`+https://www.youtube.com/watch?v=VIDEO-ID+`) and replace the video + title and link in the line under `
`. +. In YouTube, select *Share*, and then select *Embed*. +. Copy the `+++++++++ + +leave a blank line here +---- + +This is how it renders on the LinuxCNC documentation site: + +See the video: https://www.youtube.com/watch?v=enMumwvLAug[What is LinuxCNC].+++
++++++++++++
+++ + +____ +Notes: + +* The `figure` tag is required for semantic SEO +* `video-container` class is necessary to make sure the video is responsive + and displays on different mobile devices. +* The `
` is a fallback necessary for `/help`, + because the GitLab Markdown processor doesn't support iframes. It's + hidden on the documentation site, but is displayed by `/help`. +____ +//// + +[[docs:style:admonitions]] +== Admonitions + +// https://asciidoc-py.github.io/userguide.html#X28 +// https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/ + +Use admonition boxes to call attention to information. + +Use them sparingly, and never have an alert box immediately follow another +alert box. + +Single paragraph admonitions are generated when one of these uppercase +labels is used as a style attribute: + +* `NOTE` +* `TIP` +* `IMPORTANT` +* `CAUTION` +* `WARNING` +// FIXME No DISCLAIMER, nor FLAG or INFO + +Lines of the paragraph should be left aligned on the content of the first +line for better readability of the source. + +For example: + +[source,adoc] +---- +[TIP] +Ain't that a useful tip ?! +---- + +Renders as: + +[TIP] +Ain't that a useful tip ?! + +[NOTE] +This form is preferred to the `LABEL:` prefix at the beginning of the paragraph +for consistency with the multi-block admonitions markup. + +When you want to apply an admonition to more elaborate content, set the +label as a style attribute on an example block (`====`): + +[source,adoc] +---- +[NOTE] +.Admonition block can have titles +==== +Admonition blocks allow for multi block content: + +* lists +.. Nested lists + +[source] +command example +==== +---- + +Renders as: + +[NOTE] +.Admonition block can have titles +==== +Admonition blocks allow for multi block content: + +* lists +.. Nested lists + +[source] +command example +==== + + +//// +TODO FLAG admonition +=== Flag + +Use this alert type to describe a feature's availability. For information about how to format +`FLAG` alerts, see xref:../feature_flags.adoc[Document features deployed behind feature flags]. +//// + +=== Note + +Use notes sparingly. Too many notes can make topics difficult to scan. + +Instead of adding a note: + +* Re-write the sentence as part of a paragraph. +* Put the information into its own paragraph. +* Put the content under a new subheading. + +If you must use a note, use this format: + +[source,adoc] +NOTE: This is something to note. + +It renders on the LinuxCNC documentation site as: + +NOTE: This is something to note. + +=== Tip + +Use tips to add tricks and useful information from craft and experience. + + +If you must use a note, use this format: + +[source,adoc] +---- +[TIP] +This is how grandpa did it. +---- + +It renders on the LinuxCNC documentation site as: + +[TIP] +This is how grandpa did it. + +//// +TODO INFO admonition +=== Info + +The Marketing team uses the `INFO` alert to add information relating to +sales and marketing efforts. + +The text in an `INFO` alert always renders in a floating text box to the +right of the text around it. To view the rendered LinuxCNC docs site, check +the review app in the MR. You might need to move the text up or down in +the surrounding text, depending on where you'd like to floating box to +appear. + +For example, if your page has text like this: + +[source,adoc] +---- +This is an introductory paragraph. LinuxCNC uses the SSH protocol to securely +communicate with Git. When you use SSH keys to authenticate to the LinuxCNC +remote server, you don't need to supply your username and password each +time. + +INFO: Here is some information. This information is an important addition + to how you work with LinuxCNC and you might want to consider it. + +And here is another paragraph. LinuxCNC uses the SSH protocol to securely +communicate with Git. When you use SSH keys to authenticate to the LinuxCNC +remote server, you don't need to supply your username and password each +time. + +And here is another paragraph. LinuxCNC uses the SSH protocol to securely +communicate with Git. When you use SSH keys to authenticate to the LinuxCNC +remote server, you don't need to supply your username and password each +time. +---- + +It renders on the LinuxCNC documentation site as: + +This is an introductory paragraph. LinuxCNC uses the SSH protocol to securely communicate with Git. +When you use SSH keys to authenticate to the LinuxCNC remote server, +you don't need to supply your username and password each time. + +INFO: +Here is some information. This information is an important addition to how you +work with LinuxCNC and you might want to consider it. + +And here is another paragraph. LinuxCNC uses the SSH protocol to securely communicate with Git. +When you use SSH keys to authenticate to the LinuxCNC remote server, +you don't need to supply your username and password each time. + +And here is another paragraph. LinuxCNC uses the SSH protocol to securely communicate with Git. +When you use SSH keys to authenticate to the LinuxCNC remote server, +you don't need to supply your username and password each time. +//// + +=== Caution + +Use a Caution to advise the reader to act carefully (i.e., exercise care). + +[source,adoc] +CAUTION: This is something to be careful about. + +It renders on the LinuxCNC documentation site as: + +CAUTION: This is something to be careful about. + +=== Warning + +Use a warning to indicate deprecated features, or to provide a warning about +procedures that have the potential for: + +* data loss +* danger, harm, or severe consequences. + +[source,adoc] +WARNING: This is something to be warned about. + +It renders on the LinuxCNC documentation site as: + +WARNING: This is something to be warned about. + +//// +TODO DISCLAIMER admonition +=== Disclaimer + +Use to describe future functionality only. +For more information, see link:../versions.md#legal-disclaimer-for-future-features[Legal disclaimer for future features]. +//// + +[[docs:style:quoteblocks]] +== Quote blocks + +For highlighting a quoted text inside a block, use this format: + +[source,adoc] +---- +____ +This is a QuoteBlock. +____ +---- + +It renders on the LinuxCNC documentation site as: + +____ +This is a QuoteBlock. +____ + +//// +FIXME Do we want tabs in our documentation pages ? + @silopolis: really no +== Tabs + +On the docs site, you can format text so it's displayed as tabs. + +To create a set of tabs, follow this example: + +```plaintext +::Tabs + +:::TabTitle Tab One + +Here's some content in tab one. + +:::TabTitle Tab Two + +Here's some other content in tab two. + +::EndTabs +``` + +This code renders on the LinuxCNC documentation site as: + +::Tabs + +:::TabTitle Tab One + +Here's some content in tab one. + +:::TabTitle Tab Two + +Here's some other content in tab two. + +::EndTabs + +For tab titles, be brief and consistent. Ensure they are parallel, and start each with a capital letter. +For example: + +* `Omnibus package`, `Helm chart`, `Source` +* `15.1 and earlier`, `15.2 and later` + +See https://design.gitlab.com/components/tabs/#guidelines[Pajamas] for details. +//// + + +[[docs:style:terms]] +== Terms + +To maintain consistency through LinuxCNC documentation, use these styles +and terms. + +=== Describe UI elements + +Follow these styles when you're describing user interface elements in an +application: + +* For elements with a visible label, use that label in bold with matching + case. + + For example: `+Select *Cancel*+`. +* For elements with a tooltip or hover label, use that label in bold with + matching case. + + For example: `+Select *Home All*+`. + + +[[docs:style:apps]] +== Applications, components and features + +Refer to the information in this section when describing applications, +components and features in the LinuxCNC documentation. + +=== Avoid line breaks in names + +If an application, component, or feature name contains spaces, don't split +the name with a line break. + +When names change, it is more complicated to search or `grep` text that has +line breaks. + + +//// +FIXME LinuxCNC specific sections ? styles ? +[[docs:style:special-sections]] +== Specific sections + +Certain styles should be applied to specific sections. Styles for specific +sections are outlined in this section. + +=== Installation guide + +In link:../../../install/installation.md#2-ruby[step 2 of the installation guide], +we install Ruby from source. To update the guide for a new Ruby version: + +* Change the version throughout the code block. +* Replace the sha256sum. It's available on the +https://www.ruby-lang.org/en/downloads/[downloads page] of the Ruby website. + +=== Configuration documentation for source and Omnibus installations + +LinuxCNC supports two installation methods: installations from source, and Omnibus +packages. Possible configuration settings include: + +* Settings that touch configuration files in `config/`. +* NGINX settings. +* Other settings in `lib/support/`. + +Configuration procedures can require users to edit configuration files, reconfigure +LinuxCNC, or restart LinuxCNC. Use these styles to document these steps, replacing +`PATH/TO` with the appropriate path: + +[source,adoc] +---- +*For Omnibus installations* + +. Edit `/etc/gitlab/gitlab.rb`: ++ +[source,ruby] +external_url "https://gitlab.example.com" + +. Save the file and link:PATH/TO/administration/restart_gitlab.md#omnibus-gitlab-reconfigure[reconfigure] +LinuxCNC for the changes to take effect. + +''' + +*For installations from source* + +. Edit `config/gitlab.yml`: ++ +[source,yaml] +gitlab: + host: "gitlab.example.com" + +. Save the file and link:PATH/TO/administration/restart_gitlab.md#installations-from-source[restart] +LinuxCNC for the changes to take effect. +---- + +In this case: + +* Bold the installation method's name. +* Separate the methods with three dashes (`---`) to create a horizontal line. +* Indent the code blocks to line up with the list item they belong to.. +* Use the appropriate syntax highlighting for each code block. +* Use the <> section to explain any required +restart or reconfigure of LinuxCNC. + +=== LinuxCNC restart + +When a restart or reconfigure of LinuxCNC is required, avoid duplication +by linking to link:../../../administration/restart_gitlab.adoc[`doc/administration/restart_gitlab.md`] +with text like this, replacing 'reconfigure' with 'restart' as needed: + +`markdown +Save the file and [reconfigure LinuxCNC](../../../administration/restart_gitlab.md) +for the changes to take effect. +` + +If the document resides outside of the `doc/` directory, use the full path +instead of the relative link: +`+https://docs.gitlab.com/ee/administration/restart_gitlab.html+`. +//// + +//// +TODO Could this be used for LinuxCNC to help development of big changes ? +== Feature flags + +Learn how to xref:../feature_flags.adoc[document features deployed behind flags]. For +guidance on developing LinuxCNC with feature flags, see xref:../../feature_flags/index.adoc[Feature flags in development of LinuxCNC]. +//// diff --git a/docs/src/code/docs-word-list.adoc b/docs/src/code/docs-word-list.adoc new file mode 100644 index 00000000000..126c95c4da0 --- /dev/null +++ b/docs/src/code/docs-word-list.adoc @@ -0,0 +1,1187 @@ += Recommended word list +:description: Writing styles, markup, formatting, and other standards for GitLab Documentation. +:experimental: +:group: Style Guide +:info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +:stage: none + +To help ensure consistency in the documentation, the Technical Writing team +recommends these word choices. In addition: + +* The GitLab handbook contains a list of +https://about.gitlab.com/handbook/communication/top-misused-terms/[top misused terms]. +* The documentation link:../styleguide#language[style guide] includes details +about language and capitalization. + +For guidance not on this page, we defer to these style guides: + +* https://docs.microsoft.com/en-us/style-guide/welcome/[Microsoft Style Guide] +* https://developers.google.com/style[Google Developer Documentation Style Guide] + +// vale off + +// markdownlint-disable + +== `&` + +Do not use Latin abbreviations. Use *and* instead, unless you are documenting a UI element that uses an `&`. + +== `@mention` + +Try to avoid *`@mention`*. Say *mention* instead, and consider linking to the +link:../../../user/discussions/index.md#mentions[mentions topic]. +Don't use backticks. + +== 2FA, two-factor authentication + +Spell out *two-factor authentication* in sentence case for the first use and in section headings, and *2FA* +thereafter. If the first word in a sentence, do not capitalize `factor` or `authentication`. For example: + +* Two-factor authentication (2FA) helps secure your account. Set up 2FA when you first log in. + +== above + +Try to avoid using *above* when referring to an example or table in a documentation page. If required, use *previous* instead. For example: + +* In the previous example, the dog had fleas. + +Do not use *above* when referring to versions of the product. Use <> instead. + +Use: + +* In GitLab 14.4 and later... + +Instead of: + +* In GitLab 14.4 and above... +* In GitLab 14.4 and higher... + +== access level + +Access levels are different than <> or <>. +When you create a user, you choose an access level: *Regular*, *Auditor*, or *Admin*. + +Capitalize these words when you refer to the UI. Otherwise use lowercase. + +== administrator + +Use *administrator access* instead of *admin* when talking about a user's access level. + +image::img/admin_access_level.png[admin access level] + +An *administrator* is not a <> or <>. + +Use: + +* To do this thing, you must be an administrator. +* To do this thing, you must have administrator access. + +Instead of: + +* To do this thing, you must have the Admin role. + +== Admin Area + +Use title case *Admin Area* to refer to the area of the UI that you access when you select menu:Main menu[Admin]. +This area of the UI says *Admin Area* at the top of the page and on the menu. + +== agent + +Use lowercase to refer to the https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent[GitLab agent for Kubernetes]. +For example: + +* To connect your cluster to GitLab, use the GitLab agent for Kubernetes. +* Install the agent in your cluster. +* Select an agent from the list. + +Do not use title case *GitLab Agent* or *GitLab Agent for Kubernetes*. + +== agent access token + +The token generated when you create an agent for Kubernetes. Use *agent access token*, not: + +* registration token +* secret token +* authentication token + +== air gap, air-gapped + +Use *offline environment* to describe installations that have physical barriers or security policies that prevent or limit internet access. Do not use *air gap*, *air gapped*, or *air-gapped*. For example: + +* The firewall policies in an offline environment prevent the computer from accessing the internet. + +== allow, enable + +Try to avoid *allow* and *enable*, unless you are talking about security-related features. + +Use: + +* You can add a file to your repository. + +Instead of: + +* This feature allows you to add a file to your repository. +* This feature enables users to add files to their repository. + +This phrasing is more active and is from the user perspective, rather than the person who implemented the feature. +https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows[View details in the Microsoft style guide]. + +== Alpha + +Use uppercase for *Alpha*. For example: *The XYZ feature is in Alpha.* or *This Alpha release is ready to test.* + +You might also want to link to link:../../../policy/alpha-beta-support.md#alpha-features[this section] +in the handbook when writing about Alpha features. + +== and/or + +Instead of *and/or*, use *or* or rewrite the sentence to spell out both options. + +== and so on + +Do not use *and so on*. Instead, be more specific. For details, see +https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/and-so-on[the Microsoft style guide]. + +== area + +Use <> instead of *area*. The only exception is <>. + +== as + +Do not use *as* to mean *because*. + +Use: + +* Because none of the endpoints return an ID... + +Instead of: + +* As none of the endpoints return an ID... + +== associate + +Do not use *associate* when describing adding issues to epics, or users to issues, merge requests, +or epics. + +Instead, use *assign*. For example: + +* Assign the issue to an epic. +* Assign a user to the issue. + +== below + +Try to avoid *below* when referring to an example or table in a documentation page. If required, use *following* instead. For example: + +* In the following example, the dog has fleas. + +== Beta + +Use uppercase for *Beta*. For example: *The XYZ feature is in Beta.* or *This Beta release is ready to test.* + +You might also want to link to link:../../../policy/alpha-beta-support.md#beta-features[this section] +in the handbook when writing about Beta features. + +== blacklist + +Do not use *blacklist*. Another option is *denylist*. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml[`InclusionCultural.yml`]) + +== board + +Use lowercase for *boards*, *issue boards*, and *epic boards*. + +== box + +Use *text box* to refer to the UI field. Do not use *field* or *box*. For example: + +* In the *Variable name* text box, enter a value. + +== bullet + +Don't refer to individual items in an ordered or unordered list as *bullets*. Use *list item* instead. If you need to be less ambiguous, you can use: + +* *Ordered list item* for items in an ordered list. +* *Unordered list item* for items in an unordered list. + +== button + +Don't use a descriptor with *button*. + +Use: + +* Select *Run pipelines*. + +Instead of: + +* Select the *Run pipelines* button. + +== cannot, can not + +Use *cannot* instead of *can not*. You can also use *can't*. + +See also link:index.md#contractions[contractions]. + +== checkbox + +Use one word for *checkbox*. Do not use *check box*. + +You *select* (not *check* or *enable*) and *clear* (not *deselect* or *disable*) checkboxes. For example: + +* Select the *Protect environment* checkbox. +* Clear the *Protect environment* checkbox. + +If you must refer to the checkbox, you can say it is selected or cleared. For example: + +* Ensure the *Protect environment* checkbox is cleared. +* Ensure the *Protect environment* checkbox is selected. + +(For `deselect`, link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionWarning.yml[`SubstitutionWarning.yml`]) + +== checkout, check out + +Use *check out* as a verb. For the Git command, use `checkout`. + +* Use `git checkout` to check out a branch locally. +* Check out the files you want to edit. + +== CI/CD + +CI/CD is always uppercase. No need to spell it out on first use. + +== CI/CD minutes + +Use *CI/CD minutes* instead of *CI minutes*, *pipeline minutes*, *pipeline minutes quota*, or +*CI pipeline minutes*. This decision was made in https://gitlab.com/gitlab-org/gitlab/-/issues/342813[this issue]. + +== click + +Do not use *click*. Instead, use *select* with buttons, links, menu items, and lists. +*Select* applies to more devices, while *click* is more specific to a mouse. + +== cloud native + +When you're talking about using a Kubernetes cluster to host GitLab, you're talking about a *cloud-native version of GitLab*. +This version is different than the larger, more monolithic *Omnibus package* that is used to deploy GitLab. + +You can also use *cloud-native GitLab* for short. It should be hyphenated and lowercase. + +== collapse + +Use *collapse* instead of *close* when you are talking about expanding or collapsing a section in the UI. + +== confirmation dialog + +Use *confirmation dialog* to describe the dialog box that asks you to confirm your action. For example: + +* On the confirmation dialog, select *OK*. + +== Container Registry + +Use title case for the GitLab Container Registry. + +== currently + +Do not use *currently* when talking about the product or its features. The documentation describes the product as it is today. +(link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml[`CurrentStatus.yml`]) + +== default branch + +Use *default branch* to refer generically to the primary branch in the repository. +Users can set the default branch by using a UI setting. + +For examples that use the default branch, use `main` instead of <>. + +== Dependency Proxy + +Use title case for the GitLab Dependency Proxy. + +== deploy board + +Use lowercase for *deploy board*. + +== Developer + +When writing about the Developer role: + +* Use a capital *D*. +* Do not use bold. +* Do not use the phrase, *if you are a developer* to mean someone who is assigned the Developer +role. Instead, write it out. For example, *if you are assigned the Developer role*. +* To describe a situation where the Developer role is the minimum required: + ** Use: at least the Developer role + ** Instead of: the Developer role or higher + +Do not use *Developer permissions*. A user who is assigned the Developer role has a set of associated permissions. + +== disable + +See https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled[the Microsoft style guide] for guidance on *disable*. +Use *inactive* or *off* instead. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml[`InclusionAbleism.yml`]) + +== disallow + +Use *prevent* instead of *disallow*. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Substitutions.yml[`Substitutions.yml`]) + +== downgrade + +To be more upbeat and precise, do not use *downgrade*. Focus instead on the action the user is taking. + +* For changing to earlier GitLab versions, use <>. +* For changing to lower GitLab tiers, use *change the subscription tier*. + +== dropdown list + +Use *dropdown list* to refer to the UI element. Do not use *dropdown* without *list* after it. +Do not use *drop-down* (hyphenated), *dropdown menu*, or other variants. + +For example: + +* From the *Visibility* dropdown list, select *Public*. + +== earlier + +Use *earlier* when talking about version numbers. + +Use: + +* In GitLab 14.1 and earlier. + +Instead of: + +* In GitLab 14.1 and lower. + +== easily + +Do not use *easily*. If the user doesn't find the process to be easy, we lose their trust. + +== e.g. + +Do not use Latin abbreviations. Use *for example*, *such as*, *for instance*, or *like* instead. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml[`LatinTerms.yml`]) + +== email + +Do not use *e-mail* with a hyphen. When plural, use *emails* or *email messages*. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml[`SubstitutionSuggestions.yml`]) + +== enable + +See https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/e/enable-enables[the Microsoft style guide] for guidance on *enable*. +Use *active* or *on* instead. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml[`InclusionAbleism.yml`]) + +== enter + +In most cases, use *enter* rather than *type*. + +* *Enter* encompasses multiple ways to enter information, including speech and keyboard. +* *Enter* assumes that the user puts a value in a field and then moves the cursor outside the field (or presses ++++++Enter++++++). +*Enter* includes both the entering of the content and the action to validate the content. + +For example: + +* In the *Variable name* text box, enter a value. +* In the *Variable name* text box, enter `my text`. + +When you use *Enter* to refer to the key on a keyboard, use the HTML `` tag: + +* To view the list of results, press ++++++Enter++++++. + +See also <>. + +== epic + +Use lowercase for *epic*. + +See also <>. + +== epic board + +Use lowercase for *epic board*. + +== etc. + +Try to avoid *etc.*. Be as specific as you can. Do not use +<> as a replacement. + +Use: + +* You can update objects, like merge requests and issues. + +Instead of: + +* You can update objects, like merge requests, issues, etc. + +== expand + +Use *expand* instead of *open* when you are talking about expanding or collapsing a section in the UI. + +== FAQ + +We want users to find information quickly, and they rarely search for the term *FAQ*. +Information in FAQs belongs with other similar information, under an easily searchable topic title. + +== field + +Use *text box* instead of *field* or *box*. + +Use: + +* In the *Variable name* text box, enter `my text`. + +Instead of: + +* In the *Variable name* field, enter `my text`. + +However, you can make an exception when you are writing a task and you need to refer to all +of the fields at once. For example: + +. On the top bar, select menu:Main menu[Projects] and find your project. +. On the left sidebar, select menu:Settings[CI/CD]. +. Expand *General pipelines*. +. Complete the fields. + +Learn more about link:index.md#documenting-multiple-fields-at-once[documenting multiple fields at once]. + +== filter + +When you are viewing a list of items, like issues or merge requests, you filter the list by +the available attributes. For example, you might filter by assignee or reviewer. + +Filtering is different from <>. + +== foo + +Do not use *foo* in product documentation. You can use it in our API and contributor documentation, but try to use a clearer and more meaningful example instead. + +== future tense + +When possible, use present tense instead of future tense. For example, use *after you execute this command, GitLab displays the result* instead of *after you execute this command, GitLab will display the result*. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml[`FutureTense.yml`]) + +== Geo + +Use title case for *Geo*. + +== GitLab + +Do not make *GitLab* possessive (GitLab's). This guidance follows https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/trademark-guidelines/[GitLab Trademark Guidelines]. + +== GitLab.com + +*GitLab.com* refers to the GitLab instance managed by GitLab itself. + +== GitLab Helm chart, GitLab chart + +To deploy a cloud-native version of GitLab, use: + +* The GitLab Helm chart (long version) +* The GitLab chart (short version) + +Do not use *the `gitlab` chart*, *the GitLab Chart*, or *the cloud-native chart*. + +You use the *GitLab Helm chart* to deploy *cloud-native GitLab* in a Kubernetes cluster. + +== GitLab Flavored Markdown + +When possible, spell out xref:../../../user/markdown.adoc[*GitLab Flavored Markdown*]. +(link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml[`GLFM.yml`]) + +If you must abbreviate, do not use *GFM*. Use *GLFM* instead. + +== GitLab SaaS + +*GitLab SaaS* refers to the product license that provides access to GitLab.com. It does not refer to the +GitLab instance managed by GitLab itself. + +== GitLab Runner + +Use title case for *GitLab Runner*. This is the product you install. See also <> and https://gitlab.com/gitlab-org/gitlab/-/issues/233529[this issue]. + +== GitLab self-managed + +Use *GitLab self-managed* to refer to the product license for GitLab instances managed by customers themselves. + +== guide + +We want to speak directly to users. On `docs.gitlab.com`, do not use *guide* as part of a page title. +For example, *Snowplow Guide*. Instead, speak about the feature itself, and how to use it. For example, *Use Snowplow to do xyz*. + +== Guest + +When writing about the Guest role: + +* Use a capital *G*. +* Do not use bold. +* Do not use the phrase, *if you are a guest* to mean someone who is assigned the Guest +role. Instead, write it out. For example, *if you are assigned the Guest role*. +* To describe a situation where the Guest role is the minimum required: + ** Use: at least the Guest role + ** Instead of: the Guest role or higher + +Do not use *Guest permissions*. A user who is assigned the Guest role has a set of associated permissions. + +== handy + +Do not use *handy*. If the user doesn't find the feature or process to be handy, we lose their trust. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Simplicity.yml[`Simplicity.yml`]) + +== high availability, HA + +Do not use *high availability* or *HA*. Instead, direct readers to the GitLab xref:../../../administration/reference_architectures/index.adoc[reference architectures] for information about configuring GitLab for handling greater amounts of users. + +== higher + +Do not use *higher* when talking about version numbers. + +Use: + +* In GitLab 14.4 and later... + +Instead of: + +* In GitLab 14.4 and higher... +* In GitLab 14.4 and above... + +== hit + +Don't use *hit* to mean *press*. + +Use: + +* Press *ENTER*. + +Instead of: + +* Hit the *ENTER* button. + +== I + +Do not use first-person singular. Use *you*, *we*, or *us* instead. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml[`FirstPerson.yml`]) + +== i.e. + +Do not use Latin abbreviations. Use *that is* instead. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml[`LatinTerms.yml`]) + +== in order to + +Do not use *in order to*. Use *to* instead. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Wordy.yml[`Wordy.yml`]) + +== issue + +Use lowercase for *issue*. + +== issue board + +Use lowercase for *issue board*. + +== issue weights + +Use lowercase for *issue weights*. + +== job + +Do not use *build* to be synonymous with *job*. A job is defined in the `.gitlab-ci.yml` file and runs as part of a pipeline. + +If you want to use *CI* with the word *job*, use *CI/CD job* rather than *CI job*. + +== Kubernetes executor + +GitLab Runner can run jobs on a Kubernetes cluster. To do this, GitLab Runner uses the Kubernetes executor. + +When referring to this feature, use: + +* Kubernetes executor for GitLab Runner +* Kubernetes executor + +Do not use: + +* GitLab Runner Kubernetes executor, because this can infringe on the Kubernetes trademark. + +== later + +Use *later* when talking about version numbers. + +Use: + +* In GitLab 14.1 and later... + +Instead of: + +* In GitLab 14.1 and higher... +* In GitLab 14.1 and above... + +== list + +Do not use *list* when referring to a <>. +Use the full phrase *dropdown list* instead. + +== license + +When writing about licenses: + +* Do not use variations such as *cloud license*, *offline license*, or *legacy license*. +* Do not use interchangeably with *subscription*: + ** A license grants users access to the subscription they purchased, and contains information such as the number of seats they purchased and subscription dates. + ** A subscription is the subscription tier that the user purchases. + +Use: + +* Add a license to your instance. +* Purchase a subscription. + +Instead of: + +* Buy a license. +* Purchase a license. + +== limitations + +Do not use *limitations*. Use *known issues* instead. + +== log in, log on + +Do not use *log in* or *log on*. Use <> instead. If the user interface has *Log in*, you can use it. + +== lower + +Do not use *lower* when talking about version numbers. + +Use: + +* In GitLab 14.1 and earlier. + +Instead of: + +* In GitLab 14.1 and lower. + +== Maintainer + +When writing about the Maintainer role: + +* Use a capital *M*. +* Do not use bold. +* Do not use the phrase, *if you are a maintainer* to mean someone who is assigned the Maintainer +role. Instead, write it out. For example, *if you are assigned the Maintainer role*. +* To describe a situation where the Maintainer role is the minimum required: + ** Use: at least the Maintainer role + ** Instead of: the Maintainer role or higher + +Do not use *Maintainer permissions*. A user who is assigned the Maintainer role has a set of associated permissions. + +== mankind + +Do not use *mankind*. Use *people* or *humanity* instead. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml[`InclusionGender.yml`]) + +== manpower + +Do not use *manpower*. Use words like *workforce* or *GitLab team members*. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml[`InclusionGender.yml`]) + +== master + +Do not use `master`. Use `main` when you need a sample <>. +(link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml[`InclusionCultural.yml`]) + +== may, might + +*Might* means something has the probability of occurring. *May* gives permission to do something. Consider *can* instead of *may*. + +== me, myself, mine + +Do not use first-person singular. Use *you*, *we*, or *us* instead. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml[`FirstPerson.yml`]) + +== merge requests + +Use lowercase for *merge requests*. If you use *MR* as the acronym, spell it out on first use. + +== milestones + +Use lowercase for *milestones*. + +== n/a, N/A, not applicable + +When possible, use *not applicable*. Spelling out the phrase helps non-English speaking users and avoids +capitalization inconsistencies. + +== navigate + +Do not use *navigate*. Use *go* instead. For example: + +* Go to this webpage. +* Open a terminal and go to the `runner` directory. + +(link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml[`SubstitutionSuggestions.yml`]) + +== need to, should + +Try to avoid *needs to*, because it's wordy. Avoid *should* when you can be more specific. If something is required, use *must*. + +Use: + +* You must set the variable. +* Set the variable. + +Instead of: + +* You need to set the variable. + +*Should* is acceptable for recommended actions or items, or in cases where an event may not +happen. For example: + +* Although you can configure the installation manually, you should use the express configuration to +avoid complications. +* You should see a success message in the console. Contact support if an error message appears +instead. + +== note that + +Do not use *note that* because it's wordy. + +Use: + +* You can change the settings. + +Instead of: + +* Note that you can change the settings. + +== on + +When documenting how to select high-level UI elements, use the word *on*. + +Use: + +* `+On the left sidebar...+` + +Instead of: + +* Do not: `+From the left sidebar...+` or `+In the left sidebar...+` + +== once + +The word *once* means *one time*. Don't use it to mean *after* or *when*. + +Use: + +* When the process is complete... + +Instead of: + +* Once the process is complete... + +== only + +Put the word *only* next to the word it modifies. + +* You can create only private projects. + +In this example, *only* modifies the noun *projects*. The sentence means you can create one type of project--a private project. + +* You can only create private projects. + +In this example, *only* modifies the verb *create*. This sentence means that you can't perform other actions, +like deleting private projects, or adding users to them. + +== override + +Use *override* to indicate temporary replacement. + +For example, a value might be overridden when a job runs. The +original value does not change. + +== overwrite + +Use *overwrite* to indicate permanent replacement. + +For example, a log file might overwrite a log file of the same name. + +== Owner + +When writing about the Owner role: + +* Use a capital *O*. +* Do not use bold. +* Do not use the phrase, *if you are an owner* to mean someone who is assigned the Owner +role. Instead, write it out. For example, *if you are assigned the Owner role*. + +Do not use *Owner permissions*. A user who is assigned the Owner role has a set of associated permissions. + +== Package Registry + +Use title case for the GitLab Package Registry. + +== permissions + +Do not use <> and *permissions* interchangeably. Each user is assigned a role. Each role includes a set of permissions. + +Permissions are not the same as <>. + +== personal access token + +Use lowercase for *personal access token*. + +== please + +Do not use *please*. For details, see the https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please[Microsoft style guide]. + +== press + +Use *press* when talking about keyboard keys. For example: + +* To stop the command, press ++++++Control+++++++++++++C++++++. + +== profanity + +Do not use profanity. Doing so may negatively affect other users and contributors, which is contrary to the GitLab value of https://about.gitlab.com/handbook/values/#diversity-inclusion[Diversity, Inclusion, and Belonging]. + +== provision + +Use the term *provision* when referring to provisioning cloud infrastructure. You provision the infrastructure, and then deploy applications to it. + +For example, you might write something like: + +* Provision an AWS EKS cluster and deploy your application to it. + +== push rules + +Use lowercase for *push rules*. + +== register + +Use *register* instead of *sign up* when talking about creating an account. + +== Reporter + +When writing about the Reporter role: + +* Use a capital *R*. +* Do not use bold. +* Do not use the phrase, *if you are a reporter* to mean someone who is assigned the Reporter +role. Instead, write it out. For example, *if you are assigned the Reporter role*. +* To describe a situation where the Reporter role is the minimum required: + ** Use: at least the Reporter role + ** Instead of: the Reporter role or higher + +Do not use *Reporter permissions*. A user who is assigned the Reporter role has a set of associated permissions. + +== Repository Mirroring + +Use title case for *Repository Mirroring*. + +== respectively + +Avoid *respectively* and be more precise instead. + +Use: + +* To create a user, select *Create user*. For an existing user, select *Save changes*. + +Instead of: + +* Select *Create user* or *Save changes* if you created a new user or +edited an existing one respectively. + +== roles + +Do not use *roles* and <> interchangeably. Each user is assigned a role. Each role includes a set of permissions. + +Roles are not the same as <>. + +== roll back + +Use *roll back* for changing a GitLab version to an earlier one. + +Do not use *roll back* for licensing or subscriptions. Use *change the subscription tier* instead. + +== runner, runners + +Use lowercase for *runners*. These are the agents that run CI/CD jobs. See also <> and https://gitlab.com/gitlab-org/gitlab/-/issues/233529[this issue]. + +When referring to runners, if you have to specify that the runners are installed on a customer's GitLab instance, +use *self-managed* rather than *self-hosted*. + +== (s) + +Do not use *(s)* to make a word optionally plural. It can slow down comprehension. For example: + +Use: + +* Select the jobs you want. + +Instead of: + +* Select the job(s) you want. + +If you can select multiples of something, then write the word as plural. + +== sanity check + +Do not use *sanity check*. Use *check for completeness* instead. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml[`InclusionAbleism.yml`]) + +== scalability + +Do not use *scalability* when talking about increasing GitLab performance for additional users. The words scale or scaling +are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers +to the GitLab xref:../../../administration/reference_architectures/index.adoc[reference architectures] page. + +== search + +When you search, you type a string in the search box on the top bar. +The search results are displayed on a search page. + +Searching is different from <>. + +== section + +Use *section* to describe an area on a page. For example, if a page has lines that separate the UI +into separate areas, refer to these areas as sections. + +We often think of expandable/collapsible areas as *sections*. When you refer to expanding +or collapsing a section, don't include the word *section*. + +Use: + +* Expand *Auto DevOps*. + +Instead of: + +* Do not: Expand the *Auto DevOps* section. + +== select + +Use *select* with buttons, links, menu items, and lists. *Select* applies to more devices, +while *click* is more specific to a mouse. + +== self-managed + +Use *self-managed* to refer to a customer's installation of GitLab. Do not use *self-hosted*. + +== Service Desk + +Use title case for *Service Desk*. + +== setup, set up + +Use *setup* as a noun, and *set up* as a verb. For example: + +* Your remote office setup is amazing. +* To set up your remote office correctly, consider the ergonomics of your work area. + +== sign in + +Use *sign in* instead of *sign on* or *log on* or *log in*. If the user interface has different words, use those. + +You can use *single sign-on*. + +== sign up + +Use *register* instead of *sign up* when talking about creating an account. + +== simply, simple + +Do not use *simply* or *simple*. If the user doesn't find the process to be simple, we lose their trust. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Simplicity.yml[`Simplicity.yml`]) + +== since + +The word *since* indicates a timeframe. For example, *Since 1984, Bon Jovi has existed*. Don't use *since* to mean *because*. + +Use: + +* Because you have the Developer role, you can delete the widget. + +Instead of: + +* Since you have the Developer role, you can delete the widget. + +== slashes + +Instead of *and/or*, use *or* or re-write the sentence. This rule also applies to other slashes, like *follow/unfollow*. Some exceptions (like *CI/CD*) are allowed. + +== slave + +Do not use *slave*. Another option is *secondary*. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml[`InclusionCultural.yml`]) + +== subgroup + +Use *subgroup* (no hyphen) instead of *sub-group*. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml[`SubstitutionSuggestions.yml`]) + +== that + +Do not use *that* when describing a noun. For example: + +Use: + +* The file you save... + +Instead of: + +* The file *that* you save... + +See also <>. + +== terminal + +Use lowercase for *terminal*. For example: + +* Open a terminal. +* From a terminal, run the `docker login` command. + +== text box + +Use *text box* instead of *field* or *box* when referring to the UI element. + +== there is, there are + +Try to avoid *there is* and *there are*. These phrases hide the subject. + +Use: + +* The bucket has holes. + +Instead of: + +* There are holes in the bucket. + +== they + +Avoid the use of gender-specific pronouns, unless referring to a specific person. +Use a singular https://developers.google.com/style/pronouns#gender-neutral-pronouns[they] as +a gender-neutral pronoun. + +== this, these, that, those + +Always follow these words with a noun. For example: + +* Use: *This setting* improves performance. +* Instead of: *This* improves performance. +* Use: *These pants* are the best. +* Instead of: *These* are the best. +* Use: *That droid* is the one you are looking for. +* Instead of: *That* is the one you are looking for. +* Use: *Those settings* need to be configured. (Or even better, *Configure those settings.*) +* Instead of: *Those* need to be configured. + +== to-do item + +Use lowercase and hyphenate *to-do* item. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml[`ToDo.yml`]) + +== To-Do List + +Use title case for *To-Do List*. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml[`ToDo.yml`]) + +== toggle + +You *turn on* or *turn off* a toggle. For example: + +* Turn on the *blah* toggle. + +== TFA, two-factor authentication + +Use <<2fa-two-factor-authentication,*2FA* and *two-factor authentication*>> instead. + +== type + +Use *type* when the cursor remains in the field you're typing in. For example, +in a search dialog, you begin typing and the field populates results. You do not +click out of the field. + +For example: + +* To view all users named Alex, type `Al`. +* To view all labels for the documentation team, type `doc`. +* For a list of quick actions, type `/`. + +See also <>. + +== update + +Use *update* for installing a newer *patch* version of the software only. For example: + +* Update GitLab from 14.9 to 14.9.1. + +Do not use *update* for any other case. Instead, use *upgrade*. + +== upgrade + +Use *upgrade* for: + +* Choosing a higher subscription tier (Premium or Ultimate). +* Installing a newer *major* (13.0, 14.0) or *minor* (13.8, 14.5) version of GitLab. + +For example: + +* Upgrade to GitLab Ultimate. +* Upgrade GitLab from 14.0 to 14.1. +* Upgrade GitLab from 14.0 to 15.0. + +Use caution with the phrase *Upgrade GitLab* without any other text. +Ensure the surrounding text clarifies whether +you're talking about the product version or the subscription tier. + +See also <> and <>. + +== useful + +Do not use *useful*. If the user doesn't find the process to be useful, we lose their trust. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Simplicity.yml[`Simplicity.yml`]) + +== user, users + +When possible, address the reader directly, instead of calling them *users*. +Use the <>, *you*, instead. + +Use: + +* You can configure a pipeline. + +Instead of: + +* Users can configure a pipeline. + +== utilize + +Do not use *utilize*. Use *use* instead. It's more succinct and easier for non-native English speakers to understand. +(link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml[`SubstitutionSuggestions.yml`]) + +== via + +Do not use Latin abbreviations. Use *with*, *through*, or *by using* instead. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml[`LatinTerms.yml`]) + +== we + +Try to avoid *we* and focus instead on how the user can accomplish something in GitLab. + +Use: + +* Use widgets when you have work you want to organize. + +Instead of: + +* We created a feature for you to add widgets. + +One exception: You can use *we recommend* instead of *it is recommended* or *GitLab recommends*. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml[`SubstitutionSuggestions.yml`]) + +== whitelist + +Do not use *whitelist*. Another option is *allowlist*. (link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml[`InclusionCultural.yml`]) + +== yet + +Do not use *yet* when talking about the product or its features. The documentation describes the product as it is today. + +Sometimes you might need to use *yet* when writing a task. If you use +*yet*, ensure the surrounding phrases are written +in present tense, active voice. + +link:../versions.md#promising-features-in-future-versions[View guidance about how to write about future features]. +(link:../testing.md#vale[Vale] rule: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml[`CurrentStatus.yml`]) + +== you, your, yours + +Use *you*, *your*, and *yours* instead of <>. +Documentation should be from the https://design.gitlab.com/content/voice-tone/#point-of-view[point of view] of the reader. + +Use: + +* You can configure a pipeline. + +Instead of: + +* Users can configure a pipeline. + +// vale on + +// markdownlint-enable