# 2024-10-09 Talking and Doc'ing

Topic: Astro Docs Navigation
Goal: Review the past and current state of docs navigation; have good discussions and ideas

Today we'll be looking at the overall navigation experience in Astro docs, which consists of two parts:

- the navigation infrastructure and implementation itself
- the organization of content into navigable items and sub-items

**Links:**

[Interactive board](https://miro.com/welcomeonboard/d0l0OXN0NGlzUlhkbk8wV1ZJblEzdHBPZ1hYMEs4Q2NiZDFqZEcwVk9yS1JJU1YxM0VDenROVWdETTF1NGx0RnwzNDU4NzY0NjAyNzA0MDQ2NDY5fDI=?share_link_id=287073389029) - visit and see people's card sorts, and try it yourself!

[Discord thread of sidebar navigation research/resources](https://discord.com/channels/830184174198718474/1293308281392988180)

[Astro Docs multi-tabbed sidebar prototype](https://docs-sidebar-experimentation.netlify.app/)

[Astro Docs vertical link sidebar prototype](https://docs-sidebar-topics.netlify.app/)

## History

Astro Docs used to be organized mostly by **type of document**. This is helpful to let people know whether they should expect to find an API reference, or a guide on a particular topic. But as our list of features grew, that meant more and more guide pages, making the list longer, which wouldn't scale well. People were complaining that it was difficult to find the topic guide they wanted.

This is from v2, and we've added so many more since then!


We then tried to address this issue by breaking up guides further into guides *for what*: key Astro features? general web dev topics that you need to know how to do in Astro? things you get out of the box vs things you need to add on?


The problem with this structure is that it **told readers something about the features they did not already know** instead of using the reader's perspective to be able to find content they were looking for.

For example, separating by "built in" vs "add on" **teaches** the reader that content collections just work out of the box, but integrations like UI frameworks and SSR adapters are things you add and configure. Helpful navigation categories should follow what the reader already knows so that even if collapsed, they can make meaningful navigation choices.

To address this, we regrouped "guides" into "use cases", categorizing our guides instead by what they allowed the reader to achieve:


This did not, however, fix the problem of having more top-level categories with fewer items. If collapsed, then scanning the section headers important for context is easier. When expanded, it is difficult to give a top-level overview of our structure.

## Current Issues

While our categories are more "meaningful," we are already starting to see how this structure is not serving us and may not scale:

- we are already seeing areas of overlap when attempting to add or update pages
- "content" and "data" are similar concepts, especially with the new content layer API
- Is Contentful a CMS?
- they are not easy to scan at a glance
- while any one header might have sensible contents, part of navigation is choosing between mutually exclusive categories.
- You often know you're choosing the *correct* categoy by seeing that none of the others are what you want.
- "Press 1 for . . . " (how often do you wait until you hear whether there's a "better" choice?)
- We hear negative feedback about the current navigation experience:
- "I have trouble finding the page I'm looking for"
- "I feel overwhelmed looking at the sidebar"
- These could come from poorly-chosen sections/groupings, showing too much at once, a lack of scannability...
- We won't address cases here where the information is not on the "correct" or expected page. This may also be the case in some situations! But it's not the majority of our navigation problems.

## Areas of Exploration

- having some sections collapsed
- this ONLY works if you expect people NOT to need to open them to see what's inside
- more clicks on "wrong" headings = more frustration
- different category groupings
- rethinking how our content is organized so that it is where people looking for it will find it
- multiple sidebars depending on the larger nav item chosen
- tabs/vertical links to allow people to filter to one particular sidebar that is easier to scan and find what they're looking for
- these headings **must** be mutually exclusive and obvious to the reader so they are not checking inside each one
- visual tweaks to guide readers' eyes to specific sections and/or break up feelings of being overwhelmed or "wall of text" fatigue
- icons or badges?
- horizontal separator lines