Created modular glossary & key concepts by validbeck · Pull Request #181 · validmind/documentation

validbeck · May 3, 2024

Internal Notes for Reviewers

I've cleaned up the glossary page and added a few terms and sections, such as "Artificial intelligence"

Changes are live on the demo site: https://docs-demo.vm.validmind.ai/about/glossary/glossary.html

Modular glossary

This glossary is also now single-sourcing from the about/glossary folder via Quarto's includes function
The associated embed files are structured in _filename.qmd format (e.g. _validmind.qmd)
Comments in the code have been left on the relevant source files for instructional posterity

Certain entries in the glossary are "Key concepts" or part of the "Model documentation" and "Validation reports" embeds that are called on other pages (e.g. test suite)

Edit	Image
New folder structure
Main glossary file with `includes`
Nested includes in the source files

Key concepts

These live in the about/glossary/key_concepts folder
The main _key-concepts.qmd file (in turn sourcing from the folder, and also feeding into the main glossary) that gathers all these concepts togethers is in turn embedded in:

Page (demo site)	New version	Old version
Get started
Guides
Get started with the VM DevFramework
Run tests & tests suites

This enables us to edit the files in about/glossary/key_concepts instead of editing 4 pages each time!

Model documentation

In Guides > Working with model documentation the "Key concepts" section has been replaced with modular includes from the about/glossary/model_documentation folder
The associated embed files are structured in _filename.qmd format (e.g. _doc-intro.qmd)

New working with docs	Old working with docs

Validation reports

In Guides > Preparing validation reports the "Key concepts" section has been replaced with modular includes from the about/glossary/validation-reports folder
The associated embed files are structured in _filename.qmd format (e.g. _report-intro.qmd)

New validation reports	Old validation reports

Other weirdness

integrate_external_test_providers.ipynb notebook

For some reason the broken link in this notebook to implementing_custom_tests.ipynb has been overwritten even though I fixed it in another PR in the developer-framework repo even though I ran make get-source — likely my bad, I will open a new PR to fix this quirk.

Off-set anchor links

I noticed that our fixed navigation bar is causing some incorrect off-set for anchor links, such as: https://docs.validmind.ai/about/glossary.html#platform-model-inventory
I've made a note to research and potentially fix this in the future

site/about/glossary/glossary.qmd

nrichers

LGTM! This is a fantastic leap forward for our glossary. I really like how modular this is, to the point where you can assemble almost anything on a term-by-term basis. 🚀🚀🚀

There are a few comments to address but good to merge afterwards.

site/about/glossary/_developer-tools.qmd

site/about/glossary/_ai.qmd

site/about/glossary/_developer-tools.qmd

site/about/glossary/_mrm.qmd

site/about/glossary/_validmind.qmd

Co-authored-by: Nik Richers <nik@validmind.ai>

site/about/glossary/key_concepts/_test-suite.qmd

Co-authored-by: Nik Richers <nik@validmind.ai>

validbeck

Committed some suggested changes and asked some clarifying questions

site/about/glossary/_mrm.qmd

site/about/glossary/key_concepts/_test-suite.qmd

site/about/glossary/_developer-tools.qmd

site/about/glossary/_mrm.qmd

nrichers · May 7, 2024

I noticed that our fixed navigation bar is causing some incorrect off-set for anchor links, such as: https://docs.validmind.ai/about/glossary.html#platform-model-inventory

I've made a note to research and potentially fix this in the future

Maybe also put this into a Shortcut story? Definitely an issue that should be resolved at some point.

FWIW, I checked the open Quarto issues for anything related to anchors, but nothing stood out: https://github.com/quarto-dev/quarto-cli/issues?q=is%3Aissue+is%3Aopen+anchor+.

…c-4074/create-modular-glossary

nrichers · May 8, 2024

@validbeck I helped out a little bit with this PR while you were out, I hope that is OK.

Changes:

Merged main into your branch to fix merge conflicts
Changed single bullet points into paragraph text, addressing this comment.

validbeck · May 8, 2024

Thank you! I was going to need to make those changes anyway, so that saves me the work. :)

Merged main into your branch to fix merge conflicts

How do I do this? Can you show me briefly? I guess I can also Google for docs...

Should we take a look at instances of e.g. and i.e. in the docs when I change the variables as well?

nrichers · May 8, 2024

Merged main into your branch to fix merge conflicts

How do I do this? Can you show me briefly? I guess I can also Google for docs...

Happy to demo but the basic workflow from your working branch is:

git pull origin main
Manually fix any merge conflicts that are NOT in the HTML output files
quarto render to fix the HTML output file conflicts
git add --all to add the fixed files for committing in the next step
git merge --continue (git pull is a fetch & merge; the conflicts you see happen during the merge)
Complete the merge (vim commands: Esc > : > wq)
git push to update your branch on GitHub

The same basic process also applies to updating your working branch with the latest changes from main.

Should we take a look at instances of e.g. and i.e. in the docs when I change the variables as well?

The *.qmd files should be largely free of Latin abbreviations but there quite a few occurrences in content we pull out of the developer-framework repo. We should fix those at some point but it's probably more of a nice-to-have right now? Maybe just capture that in an editing story — we should look into using ChatGPT to cover 85% of our text editing, similar to what we can now do for the release notes.

validbeck · May 8, 2024

Manually fix any merge conflicts that are NOT in the HTML output files

I think I might need to see this process in action to understand it fully, but thank you for the detailed breakdown!

validbeck · May 9, 2024

I noticed that our fixed navigation bar is causing some incorrect off-set for anchor links, such as: https://docs.validmind.ai/about/glossary.html#platform-model-inventory

Maybe also put this into a Shortcut story? Definitely an issue that should be resolved at some point.

Done: sc-4381

validbeck added 3 commits May 2, 2024 16:08

Created glossary subfolder in about with subtopic qmds

eef1e60

Moved key concepts and made them modular

c7f2f16

Referenced the key concepts in documentation & validation reports

b53dd5b

validbeck added the internal Not to be externalized in the release notes label May 3, 2024

validbeck self-assigned this May 3, 2024

validbeck requested a review from nrichers May 3, 2024 22:02

nrichers requested a review from noosheenv May 6, 2024 19:49

nrichers reviewed May 6, 2024

View reviewed changes

site/about/glossary/glossary.qmd Outdated Show resolved Hide resolved

nrichers approved these changes May 6, 2024

View reviewed changes

validbeck and others added 4 commits May 6, 2024 16:12

Update site/about/glossary/_validmind.qmd

70ac344

Co-authored-by: Nik Richers <nik@validmind.ai>

Update site/about/glossary/glossary.qmd

4ad2732

Co-authored-by: Nik Richers <nik@validmind.ai>

Update site/about/glossary/_ai.qmd

71cf8c2

Co-authored-by: Nik Richers <nik@validmind.ai>

Update site/about/glossary/_mrm.qmd

10233e9

Co-authored-by: Nik Richers <nik@validmind.ai>

nrichers reviewed May 6, 2024

View reviewed changes

site/about/glossary/key_concepts/_test-suite.qmd Outdated Show resolved Hide resolved

validbeck and others added 6 commits May 6, 2024 16:15

Update site/about/glossary/_ai.qmd

60002da

Co-authored-by: Nik Richers <nik@validmind.ai>

Update site/about/glossary/_ai.qmd

af41ec6

Co-authored-by: Nik Richers <nik@validmind.ai>

Update site/about/glossary/_developer-tools.qmd

7df6375

Co-authored-by: Nik Richers <nik@validmind.ai>

Update site/about/glossary/key_concepts/_metrics.qmd

999672e

Co-authored-by: Nik Richers <nik@validmind.ai>

Update site/about/glossary/_mrm.qmd

ba23391

Co-authored-by: Nik Richers <nik@validmind.ai>

Update site/about/glossary/_mrm.qmd

27cd372

Co-authored-by: Nik Richers <nik@validmind.ai>

validbeck commented May 6, 2024

View reviewed changes

site/about/glossary/_mrm.qmd Outdated Show resolved Hide resolved

site/about/glossary/key_concepts/_test-suite.qmd Outdated Show resolved Hide resolved

site/about/glossary/_developer-tools.qmd Outdated Show resolved Hide resolved

site/about/glossary/_mrm.qmd Outdated Show resolved Hide resolved

Update site/about/glossary/_mrm.qmd

3ec2d98

nrichers added 2 commits May 7, 2024 17:26

Merge branch 'main' of github.com:validmind/documentation into beck/s…

1b09393

…c-4074/create-modular-glossary

Turn single list items into paragraph text

114c458

validbeck merged commit 92590b1 into main May 8, 2024

nrichers deleted the beck/sc-4074/create-modular-glossary branch May 8, 2024 16:43

Search code, repositories, users, issues, pull requests...

Conversation

validbeck commented May 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Internal Notes for Reviewers

Modular glossary

Key concepts

Model documentation

Validation reports

Other weirdness

integrate_external_test_providers.ipynb notebook

Off-set anchor links

Uh oh!

Uh oh!

nrichers left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

validbeck left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nrichers commented May 7, 2024

Uh oh!

nrichers commented May 8, 2024

Uh oh!

validbeck commented May 8, 2024

Uh oh!

nrichers commented May 8, 2024

Uh oh!

validbeck commented May 8, 2024

Uh oh!

validbeck commented May 9, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

validbeck commented May 3, 2024 •

edited

Loading