docs: naming conventions

6 files changed, 52 insertions, 34 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4d93c979ed..2a565574fa 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -29,10 +29,10 @@ Reporting problems
 Developer guidelines
 --------------------
 
-- Nvim developers should read `:help dev`.
-- External UI developers should read `:help dev-ui`.
-- API client developers should read `:help dev-api-client`.
-- Nvim developers are _strongly encouraged_ to install `ninja` for faster builds.
+- Read `:help dev` if you are working on Nvim core.
+- Read `:help dev-ui` if you are developing a UI.
+- Read `:help dev-api-client` if you are developing an API client.
+- Install `ninja` for faster builds of Nvim.
   ```
   sudo apt-get install ninja-build
   make distclean
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 06760fae35..14f35acce3 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -127,14 +127,20 @@ Sometimes a GUI or other application may want to force a provider to
 
 DOCUMENTATION						*dev-doc*
 
-- Do not prefix help tags with "nvim-". Use |vim_diff.txt| to document
-  differences from Vim; no other distinction is necessary.
-- If a Vim feature is removed, delete its help section and move its tag to
-  |vim_diff.txt|.
-- Move deprecated features to |deprecated.txt|.
+- "Just say it". Avoid mushy, colloquial phrasing in all documentation
+  (docstrings, user manual, website materials, newsletters, …). Don't mince
+  words. Personality and flavor, used sparingly, are welcome--but in general,
+  optimize for the reader's time and energy: be "precise yet concise".
+    - Prefer the active voice: "Foo does X", not "X is done by Foo".
+- Vim differences:
+    - Do not prefix help tags with "nvim-". Use |vim_diff.txt| to catalog
+      differences from Vim; no other distinction is necessary.
+    - If a Vim feature is removed, delete its help section and move its tag to
+      |vim_diff.txt|.
+- Mention deprecated features in |deprecated.txt| and delete their old doc.
 - Use consistent language.
-    - "terminal" in a help tag always means "the embedded terminal emulator", not
-      "the user host terminal".
+    - "terminal" in a help tag always means "the embedded terminal emulator",
+      not "the user host terminal".
     - Use "tui-" to prefix help tags related to the host terminal, and "TUI"
       in prose if possible.
 - Docstrings: do not start parameter descriptions with "The" or "A" unless it
@@ -222,13 +228,13 @@ LUA							*dev-lua*
 
 - Keep the core Lua modules |lua-stdlib| simple. Avoid elaborate OOP or
   pseudo-OOP designs. Plugin authors just want functions to call, they don't
-  want to learn a big, fancy inheritance hierarchy. So we should avoid complex
-  objects: tables are usually better.
+  want to learn a big, fancy inheritance hierarchy. Thus avoid specialized
+  objects; tables or values are usually better.
 
 
 API							*dev-api*
 
-Use this template to name new API functions:
+Use this template to name new RPC |API| functions:
     nvim_{thing}_{action}_{arbitrary-qualifiers}
 
 If the function acts on an object then {thing} is the name of that object
@@ -358,9 +364,17 @@ External UIs are expected to implement these common features:
 
 NAMING							*dev-naming*
 
-Naming is very important. Consistent naming in the API and UI helps users
-discover and intuitively understand  related "families" of things.  It reduces
-cognitive burden.
+Naming is important. Consistent naming in the API and UI helps both users and
+developers discover and intuitively understand related concepts ("families"),
+and reduces cognitive burden. Discoverability encourages code re-use and
+likewise avoids redundant, overlapping mechanisms, which reduces code
+surface-area, and thereby minimizes bugs...
+
+Naming conventions ~
+
+Use the "on_" prefix to name event handlers and also the interface for
+"registering" such handlers (on_key). The dual nature is acceptable to avoid
+a confused collection of naming conventions for these related concepts.
 
 
  vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index bf063ca69f..5d600eae99 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -576,11 +576,11 @@ If you want to exclude visual selections from highlighting on yank, use
 vim.highlight.on_yank({opts})                         *vim.highlight.on_yank()*
         Highlights the yanked text. The fields of the optional dict {opts}
         control the highlight:
-          - {higroup} highlight group for yanked region (default `"IncSearch"`)
+          - {higroup} highlight group for yanked region (default |hl-IncSearch|)
           - {timeout} time in ms before highlight is cleared (default `150`)
           - {on_macro} highlight when executing macro (default `false`)
           - {on_visual} highlight when yanking visual selection (default `true`)
-          - {event} event structure (default `vim.v.event`)
+          - {event} event structure (default |v:event|)
 
 vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {rtype}, {inclusive})
                                                        *vim.highlight.range()*
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 4b134926a2..a5fcef2800 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -6,16 +6,16 @@
 
 Differences between Nvim and Vim			       *vim-differences*
 
-Nvim differs from Vim in many ways, although editor and VimL features are
-mostly identical.  This document is a complete and centralized reference of
-the differences.
+Nvim differs from Vim in many ways, although editor and Vimscript (not
+Vim9script) features are mostly identical.  This document is a complete and
+centralized reference of the differences.
 
 				      Type |gO| to see the table of contents.
 
 ==============================================================================
 1. Configuration					    *nvim-config*
 
-- Use `$XDG_CONFIG_HOME/nvim/init.vim` instead of `.vimrc` for configuration.
+- Use `$XDG_CONFIG_HOME/nvim/init.vim` instead of `.vimrc` for your |config|.
 - Use `$XDG_CONFIG_HOME/nvim` instead of `.vim` to store configuration files.
 - Use `$XDG_DATA_HOME/nvim/shada/main.shada` instead of `.viminfo` for persistent
   session information.  |shada|
@@ -78,6 +78,8 @@ the differences.
 
 Default Mappings ~
 							*default-mappings*
+Nvim creates the following default mappings at |startup|. You can disable any
+of these in your config by simply removing the mapping, e.g. ":unmap Y".
 >
 	nnoremap Y y$
 	nnoremap <C-L> <Cmd>nohlsearch<Bar>diffupdate<CR><C-L>
@@ -101,17 +103,19 @@ nvim_cmdwin:
 MAJOR COMPONENTS ~
 
 API				|API|
-Lua scripting			|lua|
 Job control			|job-control|
-Remote plugins			|remote-plugin|
+LSP framework			|lsp|
+Lua scripting			|lua|
+Parsing engine			|treesitter|
 Providers
   Clipboard			|provider-clipboard|
   Node.js plugins		|provider-nodejs|
   Python plugins		|provider-python|
   Ruby plugins			|provider-ruby|
+Remote plugins			|remote-plugin|
 Shared data			|shada|
-Embedded terminal		|terminal|
-VimL parser			|nvim_parse_expression()|
+Terminal emulator		|terminal|
+Vimscript parser		|nvim_parse_expression()|
 XDG base directories		|xdg|
 
 USER EXPERIENCE  ~
@@ -160,7 +164,7 @@ FEATURES ~
 
 Command-line highlighting:
   The expression prompt (|@=|, |c_CTRL-R_=|, |i_CTRL-R_=|) is highlighted
-  using a built-in VimL expression parser. |expr-highlight|
+  using a built-in Vimscript expression parser. |expr-highlight|
 					*E5408* *E5409*
   |input()|, |inputdialog()| support custom highlighting. |input()-highlight|
 					*g:Nvim_color_cmdline*
@@ -413,7 +417,7 @@ TUI:
 UI/Display:
   |Visual| selection highlights the character at cursor. |visual-use|
 
-VimL (Vim script) compatibility:
+Vimscript compatibility:
   `count` does not alias to |v:count|
   `errmsg` does not alias to |v:errmsg|
   `shell_error` does not alias to |v:shell_error|
diff --git a/src/nvim/main.c b/src/nvim/main.c
index b73f5aad76..716434f32e 100644
--- a/src/nvim/main.c
+++ b/src/nvim/main.c
@@ -334,7 +334,7 @@ int main(int argc, char **argv)
     // prepare screen now, so external UIs can display messages
     starting = NO_BUFFERS;
     screenclear();
-    TIME_MSG("initialized screen early for UI");
+    TIME_MSG("init screen for UI");
   }
 
   init_default_mappings();  // Default mappings.
diff --git a/test/functional/api/server_notifications_spec.lua b/test/functional/api/server_notifications_spec.lua
index 279ede81f7..6367cc5caa 100644
--- a/test/functional/api/server_notifications_spec.lua
+++ b/test/functional/api/server_notifications_spec.lua
@@ -78,10 +78,10 @@ describe('notify', function()
   end)
 
   it('cancels stale events on channel close', function()
-      if isCI() then
-        pending('Sporadic hangs on CI (c.f., #14083). Skip until it is fixed.')
-        return
-      end
+    if isCI() then
+      pending('hangs on CI #14083 #15251')
+      return
+    end
     if helpers.pending_win32(pending) then return end
     local catchan = eval("jobstart(['cat'], {'rpc': v:true})")
     local catpath = eval('exepath("cat")')