Skip to content

Navigation Menu

Sign in
Appearance settings

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

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Docs audit p2 — Get Started#469

Merged
validbeck merged 11 commits intomainvalidmind/documentation:mainfrom
beck/sc-6525/docs-audit-p2-get-startedvalidmind/documentation:beck/sc-6525/docs-audit-p2-get-startedCopy head branch name to clipboard
Oct 16, 2024
Merged

Docs audit p2 — Get Started#469
validbeck merged 11 commits intomainvalidmind/documentation:mainfrom
beck/sc-6525/docs-audit-p2-get-startedvalidmind/documentation:beck/sc-6525/docs-audit-p2-get-startedCopy head branch name to clipboard

Conversation

@validbeck
Copy link
Collaborator

@validbeck validbeck commented Oct 9, 2024

Internal Notes for Reviewers

sc-6525

I cleaned up/clarified instructions under "Get Started", including updating some outdated screenshots: LIVE PREVIEW

@validbeck validbeck added the internal Not to be externalized in the release notes label Oct 9, 2024
@validbeck validbeck self-assigned this Oct 9, 2024
@validbeck validbeck requested a review from nrichers October 9, 2024 19:03
@github-actions
Copy link
Contributor

github-actions bot commented Oct 9, 2024

PR Summary

This pull request enhances the documentation for the ValidMind platform by restructuring and clarifying the steps involved in various processes. The changes include:

  • Reorganization of Steps: The documentation now provides a clearer, step-by-step guide for users to follow when interacting with the ValidMind platform, including cloning repositories, running notebooks, and exploring model documentation.
  • Improved Clarity: The language has been refined to improve clarity and readability, ensuring that users can easily understand the instructions.
  • Additional Context: More context has been added to various sections, such as the purpose of different steps and what users should expect to see at each stage.
  • Footnotes and References: The documentation now includes footnotes and references to guide users to additional resources and related documentation.
  • Visual Enhancements: Screenshots and images have been updated with clearer alt text to improve accessibility and understanding of the UI components.

These changes aim to improve the user experience by making the documentation more intuitive and easier to navigate.

Test Suggestions

  • Verify that all links in the documentation are working and lead to the correct resources.
  • Ensure that the step-by-step instructions are clear and can be followed without confusion.
  • Check that all images and screenshots are correctly displayed and have appropriate alt text.
  • Test the process of cloning the repository and running the notebooks as described in the documentation.
  • Validate that the footnotes and references provide useful additional information and context.

@github-actions
Copy link
Contributor

A PR preview is available: Preview URL

Copy link
Collaborator

@nrichers nrichers left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a helpful PR that makes a number of incremental improvements — LGTM! I especially like the next step topic, which is now much more useful for the different roles. :shipit:

Ideas for the future we should chat about:

  • It might be helpful to do a fairly ruthless edit for minimalism — let's target a 30% reduction in verbiage and see how far we can get. I look at these topics and often think, “this could go, and that, and that…” I'd love for us to add lightness in a future iteration of this content. We could even do a bit of pair programming on one of these topics together to develop a common approach.
  • Static screenshots in this section should be replaced with short, FAQ-style videos, which we should plan for in a sprint sometime soon. For example, the topic on registering your first model could have a one-minute video at the top that walks through the registration process and then shows where to find the model documentation and validation report.
  • We should talk to Andres about retiring Colab, leaving only two QuickStart paths (JupyterHub or cloning the GitHub repo). Colab is chronically out of date, and the process to maintain it is broken. Case in point: at the moment, the version we have in Google Drive for Colab dates from July, but the latest version in GitHub is from September, so they’re a full two months apart.

@validbeck
Copy link
Collaborator Author

It might be helpful to do a fairly ruthless edit for minimalism — let's target a 30% reduction in verbiage and see how far we can get.

Sounds good, the goal of this 1st round of audits was just accuracy & coherency & adherence to style, not necessarily "full rewrite". Can you make some related Stories encapsulating the objectives you want?

Static screenshots in this section should be replaced with short, FAQ-style videos, which we should plan for in a sprint sometime soon.

Same comment as above. :)

We should talk to Andres about retiring Colab, leaving only two QuickStart paths (JupyterHub or cloning the GitHub repo).

I can add this to the update the JH instance process, but even that isn't really being upkept. There's also a Story for automating that flow but I don't think it's getting any attention. Do you want to start the convo with Andres as to how we can automate this or remove it?

@validbeck validbeck merged commit da9e65e into main Oct 16, 2024
@validbeck validbeck deleted the beck/sc-6525/docs-audit-p2-get-started branch October 16, 2024 19:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

internal Not to be externalized in the release notes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

Morty Proxy This is a proxified and sanitized view of the page, visit original site.