Add AGENTS.md file

AGENTS.md

@@ -0,0 +1,42 @@
+# PR Review Guide for Agents
+
+As an AI agent, your primary responsibility when reviewing Pull Requests (PRs) in this repository is to ensure they adhere to our established documentation standards. All contributions must follow the guidelines outlined in the [Documentation Development and Writing Guide](writing_guide.md).
+
+## Review Checklist
+
+Before approving any PR, verify the following:
+
+1.  **Diátaxis Framework**: Ensure the content is correctly categorized into one of the four types:
+    *   **Tutorials**: Learning-oriented, step-by-step introductions.
+    *   **How-to guides**: Goal-oriented, practical instructions.
+    *   **Explanations**: Understanding-oriented, clarifications and context.
+    *   **Reference**: Information-oriented, precise and authoritative.
+
+2.  **Best Practices**: Check that the contribution follows our best practices:
+    *   Context is clearly set.
+    *   Content is structured around user flows.
+    *   The text is detailed but concise.
+    *   Clarity is prioritized over cleverness.
+    *   Terminology and formatting are consistent with existing documentation.
+    *   Content is accurate and verified against the current system.
+
+3.  **Styling & Conventions**:
+    *   **Headings**: Only one H1 (`#`) per page for the title.
+    *   **Links**:
+        *   No broken links (CI/CD will fail).
+        *   Descriptive link names (no "here").
+        *   Standardized internal link naming (`Category > ... > Page`).
+        *   External links open in a new tab (`{:target="_blank" rel="noopener"}`).
+    *   **Terminology**:
+        *   Use canonical names (e.g., NOMAD, NOMAD Oasis).
+        *   Correct usage of `backticks`, "double quotes", **bold**, and *italics*.
+        *   New terms are added to the [Glossary](reference/glossary.md).
+    *   **Code Blocks**: Fenced with language tags (e.g., ```python).
+    *   **File and Directory Structure**:
+        *   The location of the `.md` files should mirror the navigation bar.
+        *   Images and data are stored in `images/` and `data/` subdirectories next to the markdown file.
+
+4.  **Admonitions**:
+    *   Use standard admonition titles. Do not use custom titles.
+
+A thorough review against these points is crucial for maintaining the quality and consistency of our documentation.

docs/writing_guide.md

@@ -1,47 +1,105 @@
 # Documentation Development and Writing Guide
 
-This is a guide for best practices when contributing to the NOMAD documentation.
+This is a guide for best practices when contributing to the NOMAD documentation. Our goal is to make the documentation consistent, clear, and easy to navigate for all users.
 
-## No broken links!
+## Philosophy: Diátaxis
 
-Before merging make sure that the mkdocs logs do not report any broken links. This applies even if these links are not relevant to your changes. If you do not know how to address the broken links, create an issue in the GitHub repo and tag someone who you think could be of assistance.
+The NOMAD Docs follow the [Diátaxis framework](https://diataxis.fr/) for technical documentation. This framework organizes content into four distinct types, each serving a different user need:
 
-## Images and Data
+- **Tutorials**: learning-oriented, step-by-step introductions.
+- **How-to guides**: goal-oriented, practical instructions.
+- **Explanations**: understanding-oriented, clarifications and context.
+- **Reference**: information-oriented, precise and authoritative.
 
-All assets specific to an individual markdown file should be stored within an immediate sub-directory of the file, labeled accordingly. Please use `images/` and `data/` for the image and data files, respectively.
+When contributing, identify which type of documentation your addition belongs to. A clear separation will help users quickly find what they need.
 
-## File organization should mirror the navigation bar
+> **Tip:** Contributions often span multiple types. For example, a new *How-to* may also require a supporting *Explanation* page. It may help you to first draft all of your material in one place, and then reorganize it according to the Diátaxis structure.
 
-Files and sub-folders should be stored according to the navigation bar organization in `mkdocs.yml`.
+## Best Practice
 
-## Maintain the accuracy of the overview pages
+- **Set the context clearly.** For Tutorials and How-tos, define prerequisite knowledge and list additional resources at the top of the page. For Explanations, provide enough background to orient the reader.
+- **Think in user flows.** Imagine how a user encounters problems or tasks, not how the codebase is organized.
+- **Be as detailed as required, as concise as possible.** Include all steps or context the user needs, but avoid unnecessary narrative.
+- **Prefer clarity over cleverness.** Simple, direct wording beats jargon, metaphors, or over-complicated phrasing.
+- **Stay consistent.** Follow existing terminology, formatting, and naming conventions; introduce new terms sparingly and define them clearly. When in doubt, cross-check other docs pages or ask the documentation maintainers.
+- **Keep essential context in place, centralize reusable content.** Provide enough information directly on the page so the user can follow without friction. For reused, larger blocks of content, keep a single authoritative version and link to it.
+- **Check accuracy with the actual system.** Verify commands, screenshots, and examples against the current NOMAD deployment. *Only merge a docs PR after the corresponding code changes have been merged into `nomad-lab`’s `develop` branch*.
 
-If you add a new page to the docs, make sure to add this page to the corresponding overview page (when applicable).
+## Styling & Conventions
 
-## Standardized Internal and External Link Naming
+### Headings & Structure
 
-Use descriptive link text (instead of `here/link`). For internal links use the path hierarchy to the referenced page or section, separated by >'s. For example: `[Tutorial > Exploring Data > Search Interface & Filters](<path-to-referenced-section>)`. Long paths can be abbreviated to the first and last parts: by using `[Tutorial > ... > Search Interface & Filters](<path-to-referenced-section>)` If the referenced section belongs to the current page, drop the global path, i.e., `[Search Interface & Filters](<path-to-referenced-section>)`. External links to NOMAD plugins or other NOMAD-related documentation should follow the same syntax, with the name of the plugin as the root. For other external links provide some sort of descriptive name and use your discretion.
+**One H1 per page.** Use single `#` sections only at the top of the file for the page title.
 
-## External Links
+**Auto-TOC awareness:** Headings populate the Table of Contents; admonition titles do not. Use real headings for navigable sections.
 
-Use `[](){:target="_blank" rel="noopener"}` for external links to open a new browser window.
+### Links
 
-## Admonitions
+**Link checks.** Broken internal or external links will cause CI/CD to fail. Try to fix them when possible. If you cannot resolve a broken link, create an issue and tag a maintainer.
 
-Here is a list of currently used admonitions within the docs:
+**Descriptive link naming.** Do not use "here" as a name for links.
 
-- !!! warning "Attention"
+**Internal links: standardized naming.** Use the path hierarchy to the referenced page or section, separated by >'s. For example: `[Tutorial > Exploring Data > Search Interface & Filters](<path-to-referenced-section>)`. Long paths can be shortend with `...`, e.g., `[Tutorial > ... > Search Interface & Filters](<path-to-referenced-section>)`, using your best judgement.
+
+If the referenced section belongs to the current page, drop the global path, i.e., `[Search Interface & Filters](<path-to-referenced-section>)`.
+
+**External links to NOMAD-related documentation.** External links to, e.g., NOMAD plugin documentation should follow the same syntax as internal link names, with the name of the plugin as the root. For example, [NOMAD Utility Workflows > How-to Guides > Create Custom Workflows](https://fairmat-nfdi.github.io/nomad-utility-workflows/how_to/create_custom_workflows.html).
+
+**Other external links: descriptive text + new tab.** For other external links, use descriptive names, not raw URLs.
+
+**New window for external links.** All external links should use `[](){:target="_blank" rel="noopener"}` to open a new browser window.
+
+### Terminology, capitalization, and text stylizing
+
+**Use consistent, canonical names.** NOMAD, NOMAD Oasis, MongoDB, Elasticsearch, etc.
+
+**Backticks, quotes, bold, and italics.**
+
+- Use `backticks` for:
+    - Code (e.g., inline commands, file names, parameters, API endpoints, config options, environment variables).
+    - Literal values the user must type, e.g., in the UI.
+
+- Use "double quotes" when quoting actual text strings (e.g., labels in the UI, button names, error messages).
+
+<!-- TODO check bold and it usage and try to be more specific -->
+- Use **bold** for:
+    - Certain UI elements (buttons, menu items, field names).
+    - Bullet list labels for clarity.
+    - Important emphasis (but use sparingly).
+
+- Use *italics* for:
+    - Emphasis in narrative text.
+    - Terms being introduced for the first time.
 
-- !!! note
+**Add new terms to glossary.** Add new NOMAD-specific terms to the [Glossary](https://github.com/FAIRmat-NFDI/nomad-docs/blob/main/docs/reference/glossary.md). External terms/concepts should link to external definitions, when appropriate (use your best judgement).
 
-- !!! tip
+## Code, commands, and UI text
+
+**Blocks & highlighting.** Use fenced code blocks with a language tag (e.g., \`\`\`bash, \`\`\`python).
+
+**Copy-paste ready.** Commands should run as-is. If a placeholder is required, angle-bracket it and explain once: <your_token>.
+
+**UI copy.** Quote exact button/label text in bold or code.
+
+## Repo Organization
+
+**Keep the navigation structure.** The location of docs .md files should mirror the navigation bar, with subfolders named after the organizational subsections of the bar.
+
+**Images and data.** All assets specific to an individual markdown file should be stored within an immediate sub-directory of the file, labeled accordingly. Please use `images/` and `data/` for the image and data files, respectively.
+
+Sharing assets between .md files in different locations is currently not allowed. If there is an exceptional case, please create a GithHub issue and tag a relevant maintainer.
+
+## Admonitions
+
+<!-- TODO Do we want to restrict to only these? Or allow custom naming? -->
+**Do not use custom titles for admonitions.**
+Any of the standard amdonition titles are allowed. Additionally, gere is a list of "custom" titles that can be used within the docs:
+
+- !!! warning "Attention"
 
 - !!! tip "Important"
 
-<!-- the following three were added in the preparation in the tutorials pages -->
-- !!! info
-- !!! task
-- !!! example
+If you would like to propose a standard extension, create an issue with your suggestion and a example image of the new admonition.
 
 ## Adding image sliders