(DOCSP-41504, DOCSP-41866, DOCSP-41583): Adds TOC label guidance, SEO, and spelling updates. #175
Conversation
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
lindseymoore
approved these changes
Jul 30, 2024
Comment on lines
71
to
74
| - Use a consistent grammatical structure for page titles. Use a | ||
| consistent style and tone across all page titles to maintain a | ||
| unified and professional appearance. For example, use verbs to | ||
| indicate procedural content. |
There was a problem hiding this comment.
Suggested change
| - Use a consistent grammatical structure for page titles. Use a | |
| consistent style and tone across all page titles to maintain a | |
| unified and professional appearance. For example, use verbs to | |
| indicate procedural content. | |
| - Use a consistent grammatical structure, style, and tone across all page titles to | |
| maintain a unified and professional appearance. For example, use verbs to | |
| indicate procedural content. |
2 sentences could be combined for conciseness and clarity.
Comment on lines
+112
to
+113
| - TOC labels primarily aid user navigation. Users should be able to | ||
| quickly locate and go to specific sections of interest. |
There was a problem hiding this comment.
Suggested change
| - TOC labels primarily aid user navigation. Users should be able to | |
| quickly locate and go to specific sections of interest. |
Think this point could be removed or added on to the second bullet, as they say similar things: "TOC labels primarily represent the documentation's structure. They outline the hierarchy of sections and help users navigate through the
content."
sarahemlin
reviewed
Jul 30, 2024
sarahemlin
approved these changes
Jul 31, 2024
jeff-allen-mongo
approved these changes
Jul 31, 2024
| We should craft them with different considerations. | ||
|
|
||
| TOC labels and page titles can match. However, we should define them | ||
| separately even when they match as a good habit and for added |
There was a problem hiding this comment.
[Nit, minimalism]
I think we can drop "as a good habit" here.
Suggested change
| separately even when they match as a good habit and for added | |
| separately even when they match for added |
|
|
||
| - While we should craft concise titles, include enough information to | ||
| confirm to the user that they have landed in the right place. A page | ||
| title can provide a bit more detail than a TOC label. |
There was a problem hiding this comment.
[Nit, minimalism]
Suggested change
| title can provide a bit more detail than a TOC label. | |
| title can provide more detail than a TOC label. |
| - Don't include "MongoDB" in a title unless the page is a product | ||
| landing page. | ||
|
|
||
| - Aim to attract users and encourage them to click on the link. |
There was a problem hiding this comment.
[Suggestion]
To add a bit more context here, maybe we can expound on how to do this. For example:
Suggested change
| - Aim to attract users and encourage them to click on the link. | |
| - Aim to attract users and encourage them to click on the link. Include phrases users might search for, or tasks they might want to accomplish. |
| TOC Labels | ||
| ---------- | ||
|
|
||
| - While the automatic labels make it easier for us to |
There was a problem hiding this comment.
Suggested change
| - While the automatic labels make it easier for us to | |
| - While the automatic labels make it easier for writers to |
|
|
||
| - While the automatic labels make it easier for us to | ||
| update the TOC as the content evolves, long titles interfere with | ||
| efficient navigation. So, we recommend that you specify TOC labels to |
There was a problem hiding this comment.
Suggested change
| efficient navigation. So, we recommend that you specify TOC labels to | |
| efficient navigation. We recommend that you specify TOC labels to |
|
|
||
| - Craft clear and descriptive TOC labels that convey the content of | ||
| each section or page accurately. Users should understand the context | ||
| from the TOC label and its placement in the overall TOC hierarchy. |
There was a problem hiding this comment.
[Praise]
I really like the mention of the overall hierarchy here!
| each section or page accurately. Users should understand the context | ||
| from the TOC label and its placement in the overall TOC hierarchy. | ||
|
|
||
| - Avoid line-wrapping. Let the placement of the TOC label in the |
There was a problem hiding this comment.
[Question]
Just making sure I'm reading this correctly, this is saying that TOC labels should appear on a single line of text? If so, maybe we can consider framing this as what to do, rather than what not to do:
Suggested change
| - Avoid line-wrapping. Let the placement of the TOC label in the | |
| - Ensure your TOC label fits on a single line of text. Let the placement of the TOC label in the |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
I added the following TOC label guidance page and updated other pages with SEO and spelling changes.
Pull Request Process
Please read the
Style Guide Review Process
wiki page.
Contributors should take the following actions:
they will merge the PR and notify you of the merge in the Slack channel.
Pull Request Description
JIRA URLs:
Staging URL:
Build: https://workerpool-boxgs.mongodbstitch.com/pages/job.html?collName=queue&jobId=66ab8074824f175afdb22eff