From 3ab2b9df5d0cbc696b00557f46700ce8a015cdfd Mon Sep 17 00:00:00 2001
From: James Catmore <james.catmore@cern.ch>
Date: Mon, 14 Apr 2025 09:09:48 +0000
Subject: [PATCH] Updating contribution guide with general guidelines

---
 README.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/README.md b/README.md
index f79f9c9..0d191f5 100644
--- a/README.md
+++ b/README.md
@@ -82,6 +82,48 @@ python -m pyspelling -j4
 ```
 This requires that `aspell` is installed locally (e.g. `apt install aspell aspell-en`).
 
+## General guidelines
+
+Please abide by the following guidelines when adding new material to the site.
+
+### Location of source material
+
+* If you start a new topic, put the relevant pages in a directory with a logical name, and select the location in the menu structure via the top-level `mkdocs.yml` configuration file. 
+* Directories and files should have short and logical names, and if multiple strings are used they should be separated by a hyphen, e.g. `software-infrastructure` not `SoftwareInfrastructure` etc.
+
+### Internal links, locations and data
+
+Links to other pages within this site should use the following: `[Link text](/path/to/page.md)`. Omit the `docs` head directory. Don't add the domain name to internal links. Files in the same directory can just be pointed at directly with no path: `[Link text](page.md)`
+
+Make use of pre-defined data and locations where possible. For instance:
+
+ * Links to the analysis software tutorial which are still on the legacy site: `{{locations.analysisSWTutorial}}`
+ * GitLab: `{{data.athena_git_url}}/-/tree/...` or `{{data.athena_git_url}}/-/blob/...`
+
+These variables are defined in [variables.yaml](data/variables.yaml).
+
+New variables should have a meaningful name based on the topic they discuss. For example, if a topic discusses remote proxy login, it should be named 
+```
+locations.remote_proxy_login
+```
+or similar. 
+
+### Headings
+
+Each page can have only one top level heading (`# Title`) which should resemble the name on the menu. All other headings below it should be `##` or lower. Capitalise the first word of the title and all words within the title (except articles, prepositions and conjunctions).
+
+### Quoting code snippets from GitLab
+
+If you want to include a block of code from GitLab, don't copy-and-paste it but instead quote it directly, e.g.:
+
+````
+```python
+--8<-- "{{data.athena_git_url}}/-/raw/main/Control/AthenaExamples/AthExHiveAthenaPool/python/WriteHiveDataObjConfig.py"
+```
+````
+
+In this way the quoted code will update as the code on GitLab is updated.
+
 ## Site Description
 This site makes use of a few [MkDocs](https://www.mkdocs.org) markdown extensions, which you can see under `markdown_extensions:` in the [mkdocs.yml](mkdocs.yml) file, and the [macros](https://mkdocs-macros-plugin.readthedocs.io/en/latest/) plugin. This plugin allows a lot more complicated behaviour than base MkDocs, and also reads in the [variables](data/variables.yaml) file.
 
@@ -93,3 +135,4 @@ Each merge request is deployed into a staging area using [GitLab Pages parallel
 
 ## Migration
 For tips about the migration of the ATLAS software documentation from Jekyll to MkDocs, please have a look at the [Migration](MIGRATION.md) document.
+
-- 
GitLab