From fb4f0abe1467e2e5906c8f243923e243379a68ab Mon Sep 17 00:00:00 2001 From: nolade Date: Fri, 7 Aug 2026 13:20:14 -0400 Subject: [PATCH] docs-v4: Add more details and examples to the doc guidelines. Added examples, adominations, more terms. --- .../modules/developers/pages/guidelines.adoc | 412 ++++++++++++------ .../developers/partials/terminology.adoc | 83 ++-- 2 files changed, 330 insertions(+), 165 deletions(-) diff --git a/doc/antora/modules/developers/pages/guidelines.adoc b/doc/antora/modules/developers/pages/guidelines.adoc index 0f47e5e2008..8ed5362722a 100644 --- a/doc/antora/modules/developers/pages/guidelines.adoc +++ b/doc/antora/modules/developers/pages/guidelines.adoc @@ -1,211 +1,377 @@ = Documentation Guidelines -What we want to present to our readers is a set of documentation that -has the same look and feel throughout the entire documentation. This -includes matching the same 'look and feel' to what the readers get on -the corporate website or within the source docs. +We aim to give our readers a complete set of documentation that has a +consistent look and feel. This includes matching the design with what +readers see on the website and in the source documents. -== InkBridge Style Guide +== Style Guide -The CSS files manages the base settings of fonts, colours, layout etc. -Changes can be made in the file when global changes are required. -Headers/footers are handled by separate files and used to update the -branding and relevant info. +The Style Guide outlines the rules and recommendations for every +documentation page. The rules cover two things: how the prose reads +(British English, a Grade 9 reading level, a friendly tone, and an +approved word list) and how the AsciiDoc is built (xrefs, tables, +admonitions, collapsible blocks, and numbers). -=== Accessibility +Consistency is important. A reader who sees three spellings of one +term, or three ways of writing a version number, spends effort +decoding the style instead of finding the answer they need. + +The subsections below are in alphabetical order. -Accessible documents ensures equal information access for everyone and -improves the user experience. Accessible design benefits all users by -making information clearer and easier to understand. This means making -documents usable by assistive technologies and navigable for all -users. +=== Accessibility -Ensure information is accessible (tables, lists) and annotated -correctly. Diagrams/Table require titles and some call-outs where -required. (i.e. Architecture diagram). Other suggestions are outlined -in this document that include fonts, spacing, headings, etc. +Accessible documents allow everyone to access information equally. +This also improves the user experience. To improve accessibility, use +clear headings, descriptive alt text, and high colour contrast. This +supports assistive technologies and aids users with visual or hearing +impairments. + +Make your information easy to read by using clear tables and simple +lists. These formats act like a map, helping your reader navigate +complex data quickly. + +Give every diagram and table a descriptive title. For technical +drawings like engineering diagrams, add call-outs to explain key +parts. These labels guide the eye and clarify how systems connect. + +Follow the other design rules in this document to improve your layout. +Use consistent fonts, proper spacing, and organised headings. These +elements work together to create a professional look. Structured +formatting helps lessen eye strain and keeps readers focused on the +content. + +=== Admonitions + +Pick the admonition type by what happens to the reader who ignores the +box, not by how much we want their attention. Overusing WARNING trains +readers to skip all five. + +.Admonition types +[cols="1,3,2",options="header"] +|=== +| Type | Use when | Cost of ignoring it +| NOTE | Extra context that helps but isn't needed to finish the task. | Nothing breaks. +| TIP | A faster or cleaner way to do what the reader is already doing. | Nothing breaks, the reader uses a slower method. +| IMPORTANT | A step or condition the reader must not skip. | The task fails or gives the wrong result. +| CAUTION | An action that can lose data, break a running server, or need manual recovery. | Recoverable damage. +| WARNING | An action that can lock out access, expose credentials, or take down production. | Serious or hard to reverse damage. +|=== + +Keep an admonition to three sentences. Anything longer belongs in body +text under its own heading. + +Never stack two admonitions together, as readers skip both. Never open +a section with an admonition, because the reader has no context yet +for the thing they're being warned about. + +=== Capitalisation + +Use *Title Case* for all Table of Contents (TOC) entries to ensure +clear organisation. + +Use *Title Case* for your main titles and top-level headings, such as +H1 and H2. This consistency helps readers navigate your document like +a map. Ensure navigation panels match the H1 and H2 headings on +selected pages to avoid confusing users. + +Use *Sentence case* for all smaller headings from H3 to H6. This style +follows a regular sentence. Only the first word and proper nouns are +capitalised. This shows the reader that these sections provide +supporting details, not main topics. The documentation needs varying +heading styles to guide the reader through the content. + +[#collapsible] +=== Collapsible text + +Use a collapsible block for very large code snippets, programming +examples, debug outputs, or anything longer than 20 lines. This allows +us to place more information on one or two pages, and readers can +select exactly the information they need by expanding sections. + +A collapsible block is an example block (`====` delimiters) marked +with `[%collapsible]`: + +---- +.Server startup output +[%collapsible] +==== +FreeRADIUS Version 4.0.0 +Copyright (C) 1999-2026 The FreeRADIUS server project and contributors +==== +---- -=== Capitalization +Always give the block a title, as the title becomes the text the +reader clicks to expand. A block with no title shows the word +"Details" instead, which tells the reader nothing about what's inside. -The TOC is Title Case. Title Case on titles and top level subsection -titles (H1 and H2 levels). The navigation panels should render the -same title heading (H1/H2) as the selected page(s). All other headings -(H3-6) are Sentence case. +The exception is a code block (more than 20 lines) that a user needs +to copy. Keep the text or block expanded. === Font -Use a clear font that legible on-screen and large enough so it's easy -to read (accessible). Generally a non-serif font is best for screens -and works in PDFs (if required) +Use a clear font that is legible on-screen and large enough so it's +easy to read (accessible). Generally a non-serif font is best for +screens and works in PDFs (if required). -It's advisable to remove CAPS BECAUSE IT SEEMS LIKE WE'RE ALWAYS -YELLING AT OUR READERS - use bold to emphasize or italics (sparingly). -Use CAPS for all acronyms such as TCP/IP, EAP etc. +Avoid capital letters BECAUSE IT SEEMS LIKE WE'RE ALWAYS YELLING AT +OUR READERS! Use bold to emphasise or italics (sparingly) to highlight +information. Use capital letters for all acronyms such as TCP/IP and +EAP. + +The CSS files set the font family and size for every page, see +<>. === Formatting -Try to use *bold* to emphasize the information rather than italics; -there's less brain "context switching" to decipher the fonts bold -versus italic. All programming snippets must be formatted as `code` or -`code blocks`. +Use *bold* to emphasise information rather than _italics_, because +readers recognise *bold* text faster than they recognise _italic_ +text. All programming snippets must be formatted as `code` or `code +blocks`. + +Code blocks using a source such as `html`, `shell` (zsh, bash), and +`unlang` render the output text in different colours. Since there are +so many sources, we're allowing all types and will update CSS with +final colours for the output text. + +Other code blocks without a native source, keep text in the `code` or +`code block` black. -Code blocks using source such as ruby, html, shell (zsh, bash) -colourises the text. Since there are so many sources, we've opted to -remove them and keep text in the `code` or `code block` black. +The CSS files control every colour on the page, see <>. === Grammar -Use simple words (less than 5-6 syllables). Substitute/remove formal -words not recommended for software docs. Check <> section for -more information on recommended words and terms. Shorten sentences or -break into 2 sentences to ensure conciseness. +Replace words of six or more syllables with shorter terms that +translate easily. Substitute or remove formal words not recommended +for software documentation. Check the <> section for more +information on recommended words and terms. -=== Landing Pages +Shorten sentences or break them into two sentences to ensure +conciseness. -All landing pages (H1 top level sections) need introductory paragraph -and explanation of what the section contains. +=== Landing pages + +All landing pages (H1 top level sections) need an introductory +paragraph and an explanation of what the section contains. Add xrefs to all the subsections contained in this section on the top -level landing page. Users can select a topic from main page while -reading or use the navigation panel on left side. +level landing page. Users can select a topic from the main page while +reading or use the navigation panel on the left side. -=== Layout +[#layout] +=== Layout and CSS -Ensure all pages are left-justified (irregular right edge) makes the -document more accessible and increases readability. Avoid +Left-justify (irregular right edge) all pages. A left-justified page +is more accessible and increases readability. Avoid centre-justification. -CSS files control the margins and page size. +The CSS files control the design elements: fonts, colours, layout, +margins, and page size. Change one line in a CSS file and the change +applies across every page at once. -=== Localization +Headers and footers live in separate files, which keeps branding and +navigation consistent. Update a logo or a contact address in one +header file and the change reaches every page. -Remove as many gerunds (words ending in *ing*) as possible - english -doesn't translate the words easily and these verbs are confusing to -readers who's first language is not english. +[NOTE] +==== +If your page needs a CSS update, send the request with your pull +request. +==== -Check convoluted text or run-on sentencces with -xref:https://hemingwayapp.com/[Hemingway] or -xref:https://app.grammarly.com/[Grammarly] editors. The reading level -needs to be Grade 9 to ensure that the document is readable, and every -user (limited inteliigence or not) can understand what they're reading -on the first pass. +=== Localisation -=== Numbers +Remove as many gerunds (words ending in ing) as possible. English +doesn't easily translate these words. This can confuse non-native +speakers. -Numbers like 1,2,3,...up 9 are written as words. Numbers starting at -10+ are written out in numerals. +Check convoluted text or run-on sentences with +link:https://hemingwayapp.com/[Hemingway] or +link:https://app.grammarly.com/[Grammarly] editors. The reading level +should be Grade 9. This ensures the document is scannable and +readable. Most users can understand what they're reading on the first +pass. [NOTE] ==== -This is *not* applicable for `code` or `coding blocks`. These numbers -need to stay in their native formats. +Hemingway and Grammarly are third-party tools, not ours. Both have +free versions that run in a browser and are enough for checking +reading level and sentence length. Neither is required, and neither +has the last word on a rule this guide sets. ==== -Decimals numbers need to only be 2 significant digits. + +=== Numbers + +Numbers like 1, 2, 3, ... up to 9 are written as words. Numbers +starting at 10+ are written out in numerals. + +This is *not* applicable for `code` or `code blocks`. These numbers +need to stay in their native formats. + +Decimal numbers need to only be two significant digits. See -xref:https://procomm.ieee.org/using-numbers-in-technical-documents-2/[IEEE -expressing numbers] in documentation for more guidance. +link:https://procomm.ieee.org/using-numbers-in-technical-documents-2/[IEEE +expressing numbers] for more guidance. === Punctuation -Use the Oxford comma to make sentences clear & concise. Lists use -periods at the end of the sentence entry. Use unordered lists when -listing contents, or items. Use ordered list for tasks or steps. +Currently, there is one space after a period at the end of a sentence. +The source files still hold a mix of one and two spaces, and this will +change in a future release. Use the Oxford comma to make sentences +clear and concise. + +Choose the list type to match the content: + +* Use unordered lists when listing contents or items. +* Use ordered lists for tasks or steps. + +Use a period at the end of each list entry. === Spacing -All Headings have a line space after them before the first paragraph. -H1 and H2 headings need 2 line breaks before the following paragraph - -TO DO the CSS file and update heading spacing as a global change. -Spacing of 1 line between paragraphs. Only one space at the end of a -sentence is required. +All headings have a line space after them before the first paragraph. +There is also a single blank line between paragraphs. + +The recommended method is to use one space at the end of a sentence +(see the previous note in Punctuation). + +Heading spacing is set per page rather than globally in the CSS. === Spelling -International English - s is used instead of z in words like -authorisation vs authorization. By matching/spelling our words the -same as supporting docs, e.g. company website or FR software, our -readers' comphrehension increases. The reader isn't decoding what -terms are if spelt the same, or if 2 terms spelt differently mean the -same thing. An example is authorise versus authorize. +We use British or UK spelling and most words use the `s` instead of +`z`. An example is "utilise" versus "utilize". By spelling our words +the same as the supporting material, for example the company website +or the FreeRADIUS software, our readers' comprehension increases. The +reader isn't figuring out what terms mean if they're spelled the same. +They're also not determining whether two terms spelled differently +mean the same thing. + +Exception: Use the `z` form for authorization rather than +authorisation. This rule matches the same spelling of the term +`authorize` in the RFCs and codebase. === Tables Put information in tables where applicable to increase readability / -scanning. Use collapsible widgets for very large code -snippets/programming examples/debug outputs or anything that is longer -than 4 lines. This allows us to place more information on 1 or 2 pages -and readers can select exactly the information they need by expanding -sections. +scanning. See <> for hiding very long code snippets, +programming examples, or debug outputs. === Tone -*Friendly* and *informal* for users that need to feel comfortable when +*Friendly* and *informal* for users who need to feel comfortable when accessing information. The informal tone allows the use of contractions. -Remove all slang terms, remove rhetorical questions. Replace humongous -words with smaller easily translated items. Check other style guides -(Chicago/Google/Apple/Microsoft) for anything else not covered by this -page. -https://learn.microsoft.com/en-us/style-guide/global-communications/writing-tips[MS +Remove all slang terms and rhetorical questions. Check other style +guides (Chicago/Google/Apple/Microsoft) for anything else not covered +by this page. +link:https://learn.microsoft.com/en-us/style-guide/global-communications/writing-tips[MS Tips] is a good reference for technical documentation and -localization. +localisation. + +=== Xrefs and Links + +Use `xref:` for a target inside our documentation and `link:` for a +target on another site. + +Don't send an external URL through `xref:`. Asciidoctor treats the URL +as an anchor name and emits `href="#https://example.com/"`, so the +link looks right on the page and goes nowhere when clicked. -=== Xrefs +.Link syntax +[options="header,autowidth"] +|=== +| Target | Syntax | Example +| Page in the same module | `+xref:page.adoc[text]+` | `+xref:guidelines.adoc[Documentation Guidelines]+` +| Anchor on a page in the same module | `+xref:page.adoc#anchor[text]+` | `+xref:components/radius_servers.adoc#policy[Policies]+` +| Page in another module | `+xref:module:page.adoc[text]+` | `+xref:concepts:freeradius.adoc[FreeRADIUS]+` +| Anchor on the page being read | `+<>+` | `+<>+` +| Another site or external site | `+link:url[text]+` | `+link:https://docs.asciidoctor.org/[AsciiDoc]+` +|=== -RFCs need to be x-ref'd and no dash between RFC and xxxx digits. For -example, xref:https://datatracker.ietf.org/doc/html/rfc2865[RFC 2345] +To print a macro instead of running it, wrap the example in plus signs +inside the backticks: + +---- +| Page in the same module | `+xref:page.adoc[text]+` +---- + +Always put link text inside the brackets. Empty brackets print the raw +URL, which readers can't scan and screen readers read out one +character at a time. + +Every module needs its prefix when you reference a file in a different +module. A page in `howto` linking to a page in `concepts` needs +`xref:concepts:`, and leaving the prefix off resolves against `howto` +instead. + +RFCs need to be referenced with no dash between RFC and the xxxx +digits. For example, +link:https://datatracker.ietf.org/doc/html/rfc2865[RFC 2865]. == Recommendations -=== xref:https://docs.asciidoctor.org/asciidoc/latest/[Ascidocs] +=== link:https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc] + +Use the built-in functions and templates from AsciiDoc to standardise +output rendering. -Use the built in functions and templates from ascidoc to standardize -output rendering. Some tips include: +Some tips include: -* Use the Menu lisitng and the menu items function in ascidocs. For - example, `menu` function (gives the MENU>item2>item2 syntax). -* For tables, use the [options="headers,autowidth"] to uniformaly size - the columns and data. If needed, the options can be set to customize - the column size according to the data to be displayed. For example, - [cols="1,3"]. -* Use plain text for code and code snippets instead our shell=source, - or bash. The use of these parameters colorize the text and we want - to do this by modifying the CSS file. +* Use the Menu listing and the menu items function in AsciiDoc. For + example, `menu` function (gives the MENU>item1>item2 syntax). +* For tables, use `[options="header,autowidth"]` to size the columns + to fit their contents. Note that the option is `header`, not + `headers`, and the plural is silently ignored so the table renders + with no header row. +* To set the column widths yourself, use `+[cols=...]+` and drop + `autowidth`, because `autowidth` overrides any widths given in + `cols`. For example, `[cols="1,3,3",options="header"]` makes the + first column narrow and the remaining two equal. -=== Single Source +=== Single source -Add partials for any chunk repeated more that twice throughout the -docs Some examples are the mailing and RFC lists that are repeated -multiple time throughout the doc. Any diagram or image that is -required in more than one place needs to be placed in a partials -directory. +Add partials for any section of text repeated more than twice +throughout the documentation. Some examples are the mailing and RFC +lists that are repeated multiple times throughout the documentation. + +Any paragraphs or text that is required in more than one place needs +to be placed in a partials directory. + +Any diagram or image that is required in more than one place needs to +be placed in an images directory. [#terms] == Terminology -International English, or Global English, is the standard form of -English used for global communication. Using global english -prioritizes clarity and simplicity for non-native speakers in -international contexts. Seamless communication between speakers from -diverse linguistic backgrounds are possible. +We write in British English, and we keep the wording plain enough for +a global readership. Plain, simple wording prioritises clarity for +non-native speakers. Readers from diverse linguistic backgrounds can +then follow the text on the first pass. To ensure effective communication, consider the following: * Simplify language and avoid complex constructions. -* Write for translation, simpler words are easy to localize and +* Write for translation; simpler words are easy to localise and understand. * Use clear, short sentences and avoid ambiguous language. -* Try using standard expressions and avoid phrasal verbs, gerunds, and +* Use standard expressions and avoid phrasal verbs, gerunds, and colloquialisms. -* Standardize dates, phone numbers, and addresses. +* Standardise dates, phone numbers, and addresses. Worked examples are + still to be added. include::partial$terminology.adoc[] +== Antora Documentation Style Guide + +For developers contributing to the codebase, see the style guide in +the reference directory for more guidance writing your documentation +in code. + // Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/developers/partials/terminology.adoc b/doc/antora/modules/developers/partials/terminology.adoc index 12fb76fbb67..2cbaa1eae56 100644 --- a/doc/antora/modules/developers/partials/terminology.adoc +++ b/doc/antora/modules/developers/partials/terminology.adoc @@ -1,59 +1,58 @@ -The following tables indicate what are good or bad terms to use in our documentation (developer doc-in-code or customer-facing). +The following tables indicate which terms are good or bad to use in our documentation, both the developer documentation written inside the source code and the customer-facing pages. -== Words and Terms +=== Words and terms -.Words and Terms -[options="headers,autowidth"] +.Words and terms +[options="header,autowidth"] |=== -| Not recommended | Recommended | Reason -| analyze, analyzed, analyzing | analyse, analysed, analysing | Standardize on International or Global English. -| authorize, authorized,authorizing | authorise, authorised, authorising| Standardize on International or Global English. -| behavior | behaviour | Standardize on International or Global English. -| centralise, centralised, centralising | centralize, centralized, centralizing | Standardize on International or Global English. -| licence | license | For technical docs, the norm is to use license as both the noun & verb. Unlike in Canada licence=noun, license=verb. -| minimize, minimizing, minimized | minimise, minimised, minimising| Standardize on International or Global English. -| freeradius, FreeRadius | freeRADIUS, FreeRADIUS | Use a standard word for freeRADIUS so users don't think it's a different software version or product. This form most represents our logo the most. -| thus, thusly | therefore, as a result, so, thereby| Thus is a formal term and not recommended for software docs. Try rephrasing the sentence to remove the word. -| v.4.0.0, ver 4.0, v4.0.x | v4, version 4 | Standardize on one term throughout the docs. -| v.3.0.0, ver 3.0, v3.0.x | v3, version 3 | Standardize on one term throughout the docs. -| master | primary, main | Use Inclusive language. Can only change the term where/when 'primary' reference works in the selected context. Legacy terms master/slave are still to be used. -| mandatory | required, needed, must be present| Inclusive language. -| user | end-user | This term means the end-user or user clients that are accessing the network. These aren't network clients like a NAS or proxy server that talk directly to the freeRADIUS server. -| nases, NASes, Nases | NASs | NAS refers to network Access Server that may be a device or software. Many plural forms but need to standardize on one form. Currently set to NASs, but open to suggestion if we decide we want to go with NASes. -| network user(s) | end-user(s) | To differentiate between the RADIUS Server clients i.e. NAS, proxy server versus the end-user clients (windows machines, Macs). -| clients | network clients, NAS | Refers to any device that communicates directly with the RADIUS server. -| should | must, required | Need to be More direct language to instruct user what they have to do. Should implies a suggestion and not necessarily a step that's required. -| Network RADIUS, Network Radius | InkBridge Networks | Rebranding of documents. -| whilst |while | Whilst is a formal term and not recommended for software docs. +| Not recommended | Recommended | Reason +| analyze, analyzed, analyzing | analyse, analysed, analysing | Standardise on British English. +| authorise, authorised, authorising | authorize, authorized, authorizing| Use the `z` form to match the spelling of the term `authorize` in the RFCs and codebase. +| behavior | behaviour | Standardise on British English. +| centralize, centralized, centralizing | centralise, centralised, centralising | Standardise on British English. +| freeradius, FreeRadius | freeRADIUS, FreeRADIUS | Use a standard word for freeRADIUS so users don't think it's a different software version or product. This recommended form best represents the freeRADIUS logo. +| license, licensed | licence, licenced | You may see licence=noun and license=verb, but licenced (as in copyright) is an acceptable form. +| minimize, minimizing, minimized | minimise, minimised, minimising | Standardise on British English. +| thus, thusly | therefore, as a result, so, thereby| Thus is a formal term and not recommended for software documentation. Try rephrasing the sentence to remove the word. +| v.4.0.0, ver 4.0, v4.0.x | v4, version 4 | Standardise on one term throughout the documentation. +| v.3.0.0, ver 3.0, v3.0.x | v3, version 3 | Standardise on one term throughout the documentation. +| master | primary, main | Try to use inclusive language as the first option. Legacy terms master/slave may be used according to industry standard. Only use the term where/when the 'master' reference works in the selected context. +| mandatory | required, needed, must be present | Inclusive language. +| user, users, network user(s) | end-user, end-user(s) | In a RADIUS context only. An end-user is the person or client device (Windows machines, Macs) authenticating to the network. An end-user is not a network client such as a NAS or proxy server that talks directly to the freeRADIUS server. When referring to the person reading our documentation, `user` or `reader` is correct. +| nases, Nases, NASs | NASes or Network Access Servers | NAS refers to a Network Access Server that may be a devices or software. There are many plural forms, but we need to standardise on one form such as NASes. +| client, clients | network client, network clients, NAS, NASes | Refers to any device that communicates directly with the RADIUS server. +| should | must, required, need to | Use direct language to instruct the user what they have to do. Should implies a suggestion and not necessarily a step that's required. +| Network RADIUS, Network Radius | InkBridge Networks | Rebranding of documents. +| whilst | while | Whilst is a formal term and not recommended for software documentation. |=== -== Forbidden Words +=== Forbidden words -.Forbidden Words -[options="headers, autowidth"] +.Forbidden words +[options="header,autowidth"] |=== -| Not Recommended | Recommended Words | Reason -| stupid, stupidities | nonsensical, problems, issues, senseless (if referring to an action, not person.) Other suggestions - lower intelligence threshold, unwanted behaviors, unexpected results, imprudences. | Stupid is a superfluous word and not needed. -| crap, shit | problems, issues | Crap and shit are slang and hard to translate. -| retarded | not recommended, nonsensical | Use inclusive language, this word precludes 'slower than average' reader. -| hell | troublesome, gives you issues | Hell is hard to translate and alternative words can be used. -| weenie | ineffectual, problematic, weak | Weenie translates very differently into other languages and definitely not a good word to use. +| Not Recommended | Recommended Words | Reason +| stupid, stupidities | nonsensical, problems, issues, senseless (if referring to an action, not a person). Other suggestions - lower intelligence threshold, unwanted behaviours, unexpected results, imprudences. | Stupid is a superfluous word and not needed. +| crap, shit | problems, issues | Crap and shit are slang and hard to translate. +| retarded | not recommended, nonsensical | Use inclusive language. This word excludes the 'slower-than-average' reader. +| hell | troublesome, gives you issues | Hell is hard to translate and alternative words can be used. +| weenie | ineffectual, problematic, weak | Weenie translates very differently into other languages and is definitely not a good word to use. |=== -== Acronyms +=== Acronyms -Add another table of technical terms and abbreviations here. Keep running across multiple spellings and capitalisations of some of the following: +Industry-standard acronyms use capital letters. .Acronyms -[options="headers, autowidth"] +[options="header,autowidth"] |=== -| Term |Term to use | Reason -| arp, arp | ARP | Standard way to reference protocol. +| Term | Term to use | Reason +| arp, Arp | ARP | Standard way to reference protocol. | dns, Dns | DNS | Standard way to reference protocol. -| eap, eap | EAP | Standard way to reference protocol. -| ip | ip | use ip when referencing a variable or a specific instance of an IP address in code or examples. -| IP | IP | use IP when referring to the Internet Protocol or networking standards. -| tcp, Tcp, TCP | TCP/IP | Standard way to reference protocol. +| eap, Eap | EAP | Standard way to reference protocol. +| Ip, ip | IP | Use IP when referring to the Internet Protocol (IP) or networking standards. NOTE: Use ip when referencing a variable or a specific instance of an IP address in code or examples. +| ldap | LDAP | Standard way to reference protocol, but use `ldap` when referring to the `ldap` module. +| tcp, Tcp | TCP | Standard way to reference protocol. | TCPIP, TCPip, TcpIP | TCP/IP | Standard way to reference protocol. | Udp, udp | UDP | Standard way to reference protocol. |=== -- 2.47.3