You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Docs: Define a standard navigation on documentation pages. #2260
In our documentation, we have several internal and external links and we don't have standard navigation, that is, on some pages all the links open in the same tab, in others they open using target="_blank". We need to define a navigation standard for the best user experience. We can define the following types of links:
1 - Anchors - we will not use {target="_blank"}
2 - Links to other sections of the Powertools documentation - we will not use {target="_blank"}
3 - Links to external Amazon/AWS documentation or Github AWS repositories - we'll use {target="_blank"}
4 - Third-party links - we will use {target="_blank"}
Is this related to an existing documentation section?
No response
How can we improve?
Create a linear navigation experience.
This should be considered in other runtimes.
Got a suggestion in mind?
No response
Acknowledgment
I understand the final update might be different from my proposed suggestion, or refused.
changed the title [-]Docs: Define a standard of navigation on documentation pages.[/-][+]Docs: Define a standard navigation on documentation pages.[/+]on May 14, 2023
Great to see this!! 2, 3, and 4 should be target="_blank" because the context switches.
Take 2 that is more ambiguous as an example
If you're reading about Idempotency, you might take an interest to learn more about Batch when going slightly more advanced. Changing the current view to Batch now gives two drawbacks:
You might continue to read in Batch and have multiple navigations to return from ("back" -> "back" -> "back")
You might have wanted to give that code a try before you learned more about Batch ("Batch" -> "back" -> "Idempotency")
These have a cognitive overhead in the short-term memory, making it more expensive to compute where you were in the first place, since your buffer (short-term memory) overflows.
IIRC there was a plugin to make links external more easily so we wouldn't make this error-prone mistake of forgetting the right tag etc.
Activity
[-]Docs: Define a standard of navigation on documentation pages.[/-][+]Docs: Define a standard navigation on documentation pages.[/+]heitorlessa commentedon Jun 5, 2023
Great to see this!! 2, 3, and 4 should be
target="_blank"because the context switches.Take 2 that is more ambiguous as an example
If you're reading about Idempotency, you might take an interest to learn more about Batch when going slightly more advanced. Changing the current view to Batch now gives two drawbacks:
These have a cognitive overhead in the short-term memory, making it more expensive to compute where you were in the first place, since your buffer (short-term memory) overflows.
IIRC there was a plugin to make links external more easily so we wouldn't make this error-prone mistake of forgetting the right tag etc.
github-actions commentedon Jun 8, 2023
This issue is now closed. Please be mindful that future comments are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.
github-actions commentedon Jun 16, 2023
This is now released under 2.17.0 version!