Merge branch 'update_general_guidelines' into 'main'

Draft: Updating contribution guide with general guidelines

See merge request !88

README.md

@@ -82,6 +82,37 @@ 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
+
+Markdown source files should be located within the following directory structure:
+
+ * The top level directory immediatety underneath `docs` should correspond to the top menu bar under which the new page will sit (currently `athena`, `trigger`, `software-infrastructure`
+ * Lower directories should match the sidebar menu structure, so for example the material in the Athena configuration tutorial, which falls under the "Athena Configuration" sidebar item and then the "Configuration tutorial" submenu, is likewise in the following directory: `athena/configuration/tutorial`
+ * Directories should have a short and logical name, and if multiple strings are used they should be separated by a hyphen, e.g. `software-infrastructure` not `SoftwareInfrastructure`a etc.
+
+If you feel that a new menu bar item is needed, please discuss this in advance with the (software coordinators)[mailto:atlas-software-coordinators@cern.ch] as this is a major change to the layout of the site.
+
+### 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.
+
+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 [here](https://gitlab.cern.ch/atlas/software-docs/atlas-software-docs/-/blob/main/data/variables.yaml?ref_type=heads)
+
+If you want to add a new location variable, please follow the existing convention of leading the variable name with the top menu name followed by an underscore (e.g. `athena_`, `infrastructure_`).
+
+### 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.
+
 ## 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 +124,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.
+