docs-v4: Add more details and examples to the doc guidelines. Added examples, adomina...

diff --git a/doc/antora/modules/developers/pages/guidelines.adoc b/doc/antora/modules/developers/pages/guidelines.adoc
index 0f47e5e2008a980f0a2cbee58c8e795ddf6be663..8ed5362722a4e735b9285f51ef75d9a951e4c260 100644 (file)
--- a/doc/antora/modules/developers/pages/guidelines.adoc
+++ b/doc/antora/modules/developers/pages/guidelines.adoc
@@ -1,211 +1,377 @@
 = Documentation Guidelines
 
 = 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
 
 
 === 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
+<<layout>>.

 
 === Formatting
 
 
 === 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 <<layout>>.

 
 === Grammar
 
 
 === Grammar
 

-Use simple words (less than 5-6 syllables). Substitute/remove formal
-words not recommended for software docs. Check <<terms>> 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 <<terms>> 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
 
 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.
 
 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]
 ====
 
 [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
 
 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
 
 
 === 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
 
 
 === 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
 
 
 === 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 /
 
 === 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 <<collapsible>> for hiding very long code snippets,
+programming examples, or debug outputs.

 
 === Tone
 
 
 === 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.
 
 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
 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         | `+<<anchor,text>>+`               | `+<<terms,Terminology>>+`
+| 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
 
 
 == 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
 
 
 [#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.
 
 
 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.
 
   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.
 
   colloquialisms.
 

-* Standardize dates, phone numbers, and addresses.
+* Standardise dates, phone numbers, and addresses. Worked examples are
+  still to be added.

 
 include::partial$terminology.adoc[]
 
 
 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.
 // 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 12fb76fbb675853637ebcdd144d2a044e9f8b6d2..2cbaa1eae563a09b03bd9181cf6c36247e18f85c 100644 (file)
--- 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
 
 .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.
 | 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.
 |===
 | TCPIP, TCPip, TcpIP   | TCP/IP        | Standard way to reference protocol.
 | Udp, udp              | UDP           | Standard way to reference protocol.
 |===