From 4256ec196390857674536ddf6f274c8ba9eedb5f Mon Sep 17 00:00:00 2001
From: bwbohl <b.w.bohl@gmail.com>
Date: Wed, 31 May 2023 16:52:04 +0200
Subject: [PATCH] Update CONTRIBUTING.md

* fix typos
* add section on xqDoc
* restructure
---
 CONTRIBUTING.md | 48 +++++++++++++++++++++++++++++-------------------
 1 file changed, 29 insertions(+), 19 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index baf708cc..80e39c2f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,47 +2,57 @@
 
 # General Guidelines
 
-* do not combine code-linting and contet work in one commit
+* do not combine code-linting and content work in one commit
 
 ## Whitespace handling
 
 1. Use whitespaces, not tabs to indent code
-2. Close file with newline character 
+2. Close file with a newline character
 
 
 # XQuery
 
-## XQuery version
+## xqDoc
+
+We use [xqDoc](https://xqdoc.org) for documenting the XQueries in this repository. Please refer to the section [xqDoc Comments](https://xqdoc.org/xqdoc_comments_doc.html) of the xyDoc-website for details on formatting the documentation comment blocks.
+
+* XQuery modules must have a library module xqDoc comment preceding the module declaration.
+* Function declarations must have a library module xqDoc function comment preceding the function.
+
+## XQuery document structure
+
+### XQuery version
 
 ```xquery
-xquery version 3.1
+xquery version 3.1;
 ```
 
-## Version Statement
+### License Statement
 
 ```xquery
 (:
-For LICENSE-Details please refer to the LICENSE file in the root directory of this repository. 
+For LICENSE-Details please refer to the LICENSE file in the root directory of this repository.
 :)
 ```
 
-## Module imports
-
-1. declare namespaces
-2. import module namespaces of registered modules
-3. import module namespaces of custom modules
+### File Header
 
-* Sort all three alphabetically.
-* Always use relative URIs for `import module namespace` statements that import for modules not registered with eXist-db.
+1. `declare namespace` statements
+   * sort alphabetically by prefix
+2. `import module namespace` statements of registered modules
+   * sort alphabetically by prefix
+3. `import module namespace` statements of custom modules
+   * sort alphabetically by prefix
+   * Always use relative URIs for `import module namespace` statements that import for modules not registered with eXist-db.
 
-## Declare variables
+### Declare variables
 
-* Use declare function statements for all required external parameters
+* Use `declare variable` statements for all required external parameters
 
-## Function declarations
+### Function declarations
 
-* functions have to be preceeded by a XQDoc code-block
+* functions have to be preceded by an xqDoc comment
 
-## Strings
+### XQuery body
 
-* escape with single upper straight quote  
\ No newline at end of file
+* Strings: escape with U+00027 APOSTROPHE: `'`
\ No newline at end of file