Restructured docs site layout#232
Restructured docs site layout#232validbeck merged 41 commits intomainvalidmind/documentation:mainfrom beck/sc-4799/restructuring-of-docs-site-layoutvalidmind/documentation:beck/sc-4799/restructuring-of-docs-site-layoutCopy head branch name to clipboard
Conversation
nrichers
left a comment
There was a problem hiding this comment.
Epic PR, @validbeck! 🚀🚀🚀 LGTM, as in "looks GREAT to me"!
Some general comments that should be addressed before you merge:
site/assetsandsite/imagesseem to fulfil similar purposes but the naming of the latter is more restrictive. I'm inclined to suggest we get rid of ONE of these, but my preference would actually be to keepsite/assets, as we might have other assets in the future that might need maintaining centrally (e.g. video how-to snippets, or the ValidMind schema docs that are currently just shoehorned into a QMD file, never to be maintained again).- Related, we should delete
site/assets/bootstrapas those files were for the old HTML home page and should no longer be referenced from anywhere. - For consistency with our naming convention, should
site/guidebe renamed tosite/guides? I realize we don't quite follow this convention for/site/developer, either, but there is a good reason for that — a rename of the dev framework is around the corner.
restapi.qmd
Looking at what's left in the root of site/guides, I noticed we this restapi.qmd file as well. I think this file can be deleted safely, likely an early fever dream back from when I was creating our initial docs site. There's no REST API today, the only thing that would qualify is the backend API which we don't externalize.
get-started-sandbox.qmd
site/guide/get-started-sandbox.qmd should be deleted and any links to it should point to site/training/training-overview.qmd instead. We did give a link to a prospective customer at some point, but they have since received the current link with the training modules. If anything, we don't want them going to the old link, as it's no longer current.
Links were getting unwieldy, as more things got moved into sub-directories. Where possible, instead of the ../../../ etc, I simply began with the root folder.
This is a very helpful convention and might belong into our style guide, if it's not there already?
I did some searches for external documentation links ... and created this Notion tracker
Looks like we need to add our organization-level readme to that list as it currently contains some broken links.
The source lives in https://github.com/validmind/.github/blob/main/profile/README.md — I'll add you to the repo.
The rest looks great! I'm genuinely impressed by how quickly you were able to make these file changes.
Yes, those were probably built by Ecem as they were there when I got here. I think I don't see what you see, because what I see is:
I think we're OK like this, especially if in the future we want to add a sub-directory like
I put this into
Great point, I considered it but I wasn't quite sure if that fit. I put it in the README, however:
🫡 Done! (I will also remove the closed beta update when I get to editing that file...) |
* Added Generate with AI (BETA) to Work with content blocks * Pulled in latest from main (PR##232) * Hid the Generate with AI content when rendered in HTML * Rendered site
Internal Notes for Reviewers
Style guide
File renaming
/guide/quickstart-try-developer-framework-with-jupyterhub.qmd/get-started/developer/try-with-jupyterhub.qmd/guide/quickstart-try-developer-framework-with-colab.qmd/get-started/developer/try-with-colab.qmd/guide/quickstart-try-developer-framework-in-your-own-developer-environment.qmd/get-started/developer/try-in-your-own-environment.qmd/guide/quickstart-explore-sample-model-documentation.qmd/get-started/platform/explore-sample-model-documentation.qmd/guide/quickstart-register-your-first-model.qmd/get-started/platform/register-your-first-model.qmd/guide/quickstart-generate-documentation-for-your-model.qmd/get-started/platform/generate-documentation-for-your-model.qmdAssets
Conceptual overviews
These technically don't follow the naming convention you specified @nrichers, but I figured they were close enough that it wasn't a big deal so I did not rename them:
/about/overview-model-risk-management.qmd/about/overview-model-documentation.qmdPlaceholder files
These files are marked as
search: falseso that only the right version of the articles will come up:/guide/samples-jupyter-notebooks.qmd/guide/get-started-developer-framework.qmd/guide/register-models-in-model-inventory.qmd/guide/join-community.qmd/guide/working-with-model-documentation.qmd/guide/testing-overview.qmd/guide/get-started.qmd/guide/swap-documentation-templates.qmd/guide/collaborate-on-documentation-projects.qmd/guide/supported-models.qmdSpecial attention links
HTML links
Training modules
Other edits
Duplicate column margin numbers
Simplified relative links
../../register-models-in-inventory.qmd/guide/model-inventory/register-models-in-inventory.qmdsite-unused&wip.qmds or assets I sorted intosite-unusedwipOther files
get-started-sandbox.qmd
restapi.qmd