Skip to content

Added "Documentation Overview" to Working with model documentation #198

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

Conversation

validbeck
Copy link
Collaborator

Internal Notes for Reviewers

For sc-4038, I added a Document Overview section on "Working with model documentation".

Working with model documentation

Looking to get started as a model developer?

Made a small cosmetic change to this call-out to adhere to our style guide emphasis rules.

Old New
Screenshot 2024-05-21 at 5 05 03 PM Screenshot 2024-05-21 at 5 05 09 PM

Document Overview

Modified the old Get started section into:

  • Introduction and content summary of the Document Overview
  • Add or edit documentation (Second half of the old Get started section)
Old New
Screenshot 2024-05-21 at 12 20 02 PM Screenshot 2024-05-21 at 5 06 10 PM

Assign documentation section statuses

Changed references to "documentation overview" to Document Overview as this is the official title in the UI.

@validbeck validbeck added the internal Not to be externalized in the release notes label May 22, 2024
@validbeck validbeck self-assigned this May 22, 2024
@validbeck validbeck requested a review from nrichers May 22, 2024 00:08
@validbeck validbeck changed the title Beck/sc 3831/documentation implement new documentation Added "Documentation Overview" to Working with model documentation May 22, 2024
@validbeck
Copy link
Collaborator Author

I've made some changes to the Document Overview section as I noticed sc-3817 was related to this current Story. :)

Old New
Screenshot 2024-05-21 at 5 06 10 PM Screenshot 2024-05-22 at 9 38 47 AM

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.

LGTM, with some minor comments to address. Let me know if you want to chat about conventions to make sure we're both consistent. 🚢

@validbeck
Copy link
Collaborator Author

Thank you for making these changes! You marked this as "changes requested" but what do you want me to update, @validbeck? Your comment doesn't say.

Done!

  • Avoid "can" if you can, just state the action (advice from a long-time editor I worked with).
  • In this case, "Status" isn't a proper noun, so maybe just a plain reference to "the status drop down" is enough, without bolding?
  • Changed as many of the "can"s to just the action as I could swing
  • Done!

Musing on writing minimalism ... I've also had editors suggest not to use language that refers to senses not everyone has access to

Agreed after consideration, removed.

  • AFAIK, "Status" is not a proper noun and "Document Overview" is the name of a page, so it might help to just include that.
  • Not a strong opinion, but I find that page name a bit confusing as it's not shown when you first click on the overview
  • Done!
  • Also agreed 😆
Just one can now :p (aka all the cans I have left before I can't) Simplified the status drop-down instructions
Screenshot 2024-05-22 at 2 15 00 PM Screenshot 2024-05-22 at 2 15 22 PM

@validbeck validbeck merged commit 9551c46 into main May 22, 2024
@validbeck validbeck deleted the beck/sc-3831/documentation-implement-new-documentation branch May 22, 2024 21:18
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