changes and new content on Documentation - Home tab - #115
Open
khatamirad wants to merge 10 commits into
Open
Conversation
changes are: - Intro — new paragraph added above the existing one - Schema section — removed. This already exists as a separate tab and reappearing under home was redundant. - Horizontal dividers — added at four points new content added: - Not sure where to start?" sectionNot sure where to start?" section, with mention of a to-be-developed tool (metadata checker)
Contributor
|
Added a section about downloading the CoreMeta4Cat metadata list and mentioned an upcoming Metadata Checker tool.
## Changes made ### 1. New opening paragraph added **Original:** Page opened directly with the four-pillar technical summary table (twelve preparation methods, twenty-eight techniques, etc.) **Revised:** A short plain-language opening paragraph added before everything else: > "CoreMeta4Cat defines the minimum information that should be reported alongside catalysis research data, across four domains: Synthesis, Characterization, Reaction, and Simulation. This page gives you a structured overview of what the standard covers, how it is organized, and how the different parts connect." **Reason:** A researcher clicking "Overview" expects to understand what the standard is before seeing how many preparation methods it covers. The original page led with counts and schema terms, which is the right content for developers but the wrong opening for a general audience. ### 2. Technical summary table moved **Original:** The four-bullet technical summary (twelve preparation methods, twenty-eight techniques, eight reactor design types, four computational methods) appeared at the very top of the page. **Revised:** This content is now absorbed into the four data class descriptions lower on the page, where each section naturally introduces its own counts and scope. The standalone table at the top is removed. **Reason:** Leading with counts before context reads as inside knowledge. The same information is more useful and more readable when it appears inside the section it describes. ### 3. One sentence added to "What is CoreMeta4Cat?" **Original:** The section described the technical implementation (LinkML, DCAT-AP-PLUS, generated artefacts) without saying what this means practically for a researcher. **Revised:** One sentence added at the end of the section: > "In practical terms: a dataset described with CoreMeta4Cat is not just a well-labelled spreadsheet. It is a structured, machine-readable record that can be validated, searched, and connected to other datasets across repositories — because every field links back to a shared scientific vocabulary." **Reason:** Consistent with the sentence added to the Home page intro — surfaces the semantic/knowledge graph benefit in plain language before the reader encounters the technical explanation. ### 4. "Pillars" → "data classes" throughout **Original:** The four domains were consistently called "pillars" on this page. **Revised:** Changed to "data classes" throughout — section heading changed from "The four CoreMeta4Cat pillars" to "The four data classes." **Reason:** "Data class" is the term used in the schema, the Excel workbook, the README, and the Home page. "Pillar" is an informal internal term that doesn't appear elsewhere in the documentation. Using consistent terminology reduces confusion for anyone reading across multiple pages. ### 5. Source code link corrected **Original:** `[HendrikBorgelt/CoreMeta4Cat](https://github.com/nfdi4cat/CoreMeta4Cat)` — the link text named a personal fork while the URL correctly pointed to the official repo. **Revised:** `[nfdi4cat/CoreMeta4Cat](https://github.com/nfdi4cat/CoreMeta4Cat)` — link text corrected to match the URL. **Reason:** A visitor reading "HendrikBorgelt/CoreMeta4Cat" would reasonably assume the project is maintained by an individual rather than the NFDI4Cat organization — which is both factually incorrect and potentially off-putting for institutions evaluating adoption. ### 6. "Source code" section renamed to "Further reading" **Original:** Final section was titled "Source code" and mixed the GitHub link with the documentation table. **Revised:** Renamed to "Further reading" — table retained, GitHub link moved to a separate line below the table. **Reason:** "Source code" as a section heading implies the page is for developers. "Further reading" is more neutral and welcoming to all audiences.
## Changes made ### 1. "Pillars" → "data classes" throughout **Original:** The page consistently used "the four pillars" — section heading "The four pillars", references throughout to "the four pillars", Pattern 4 referring to "pillars". **Revised:** Changed to "the four data classes" throughout. Section heading changed from "The four pillars" to "The four data classes". **Reason:** Consistent with the terminology change applied to the Overview page and used throughout the README and Home page. "Data class" is the term used in the schema itself; "pillar" is informal and doesn't appear in the schema source. ### 2. GitHub link corrected **Original:** Header GitHub link pointed to `https://github.com/HendrikBorgelt/CoreMeta4Cat` (personal fork). **Revised:** Corrected to `https://github.com/nfdi4cat/CoreMeta4Cat` (official repository). **Reason:** Same issue as Getting Started and Overview pages — same root cause, same fix. Worth noting this link appears in the MkDocs configuration (`mkdocs.yml`) rather than in the page source, so it may need to be fixed at the config level rather than per-page. Flag to co-developers. ### 3. Code block language tags added **Original:** All YAML code blocks were plain fenced blocks with no language specifier. **Revised:** All YAML blocks tagged as ` ```yaml `, the import hierarchy block tagged as plain ` ``` ` (since it's a diagram, not valid YAML). **Reason:** MkDocs Material renders syntax highlighting when a language tag is present. No content changed. ### 4. Pattern summary blocks — tag changed for clarity **Original:** Pattern summaries used a plain `??? abstract` collapsible block with the label "Pattern summary". **Revised:** Retained as-is for Patterns 1, 2, 3, and 4. The Deep dive warning block retained as `??? warning`. **Reason:** No change needed — the collapsible pattern summary blocks are well-designed and should stay exactly as they are. ### 5. Operando experiments callout — formatting made consistent **Original:** The operando experiments note under Reaction appeared as a plain indented block. **Revised:** Converted to a `??? info "Operando experiments"` collapsible block, consistent with the pattern summary blocks used elsewhere on the same page. **Reason:** Visual consistency within the page — the operando note is supplementary detail, the same role the pattern summaries play.
Another .md file was uploaded, but the naming was wrong (design_pattern.md instead of design-pattern.md) This file is being deleted to allow renaming the updated file taking over.
| # | Type | Location in page | Description | |---|---|---|---| | 1 | Added | Top of page, after opening sentence | Audience routing notice (`!!! note`) for non-developer visitors | | 2 | Edited | "Before you start" block | Converted from plain indented block to `!!! tip` admonition | | 3 | Edited | Throughout | "pillars" → "data classes" for terminology consistency | | 4 | Added | All YAML code blocks | Language tags added for syntax highlighting | | 5 | Edited | Mixin scope callout | Converted from plain block to `!!! tip` admonition |
| # | Type | Location in page | Description | |---|---|---|---| | 1 | Edited | Opening paragraph | Rewritten to accurately describe what the page does | | 2 | Added | After opening paragraph | New "Who is CoreMeta4Cat for?" section — five user-type subsections | | 3 | Added | After user-type subsections | New "How different groups use CoreMeta4Cat" routing table | | 4 | Edited | "Are you using CoreMeta4Cat?" | Converted to `!!! info` callout within "Projects and repositories" section | | 5 | Fixed | Two locations | GitHub links corrected from personal fork to official repository |
| # | Type | Location in page | Description | |---|---|---|---| | 1 | Added | Between all sections | Horizontal dividers for visual section separation | | 2 | Edited | Citation section | "still pending" → "in preparation" | | 3 | Added | Citation section | Zenodo DOI badge | | 4 | Added | Contact and Contributions | Sentence linking to NFDI4Cat community channels | | 5 | Edited | Funding table | Column alignment normalised |
| # | Type | Location in page | Description | |---|---|---|---| | 1 | Added | "Contribute code or schema changes" section | Link to How to Extend page | | 2 | Edited | "Contribute code or schema changes" section | Parentheses → em dash (stylistic) | | 3 | Added | Bottom of page | New "Not sure where to start?" closing section |
Collaborator
|
This PR converts several admonitions from !!! to ??? (collapsible) syntax in design-patterns.md and how-to-extend.md (e.g. "Operando experiments", the three "Pattern summary" boxes, and the two "Technical section" boxes). However, mkdocs.yml only enables the admonition extension, not pymdownx.details, which is required for ??? collapsible blocks to render. As-is, these six boxes will render as broken/raw text instead of styled callouts. |
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
changes are:
new content added: