Skip to content

Docs: Define a standard navigation on documentation pages. #2260

Closed

Description

@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.

Activity

  1. changed the title [-]Docs: Define a standard of navigation on documentation pages.[/-] [+]Docs: Define a standard navigation on documentation pages.[/+] on May 14, 2023
  2. heitorlessa commented on Jun 5, 2023

    @heitorlessa
    Contributor

    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.

  3. github-actions commented on Jun 8, 2023

    @github-actions
    Contributor

    ⚠️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.

  4. github-actions commented on Jun 16, 2023

    @github-actions
    Contributor

    This is now released under 2.17.0 version!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions