Docs: Define a standard navigation on documentation pages.

[leandrodamascena]

What were you searching in the docs?

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.

[heitorlessa]

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:

1. You might continue to read in Batch and have multiple navigations to return from ("back" -> "back" -> "back")
2. 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.

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

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]

This is now released under 2.17.0 version!