I’ve been working on an SST app for the last while, teaching myself mostly from the Docs and the Guide, and there are some real pain points that I keep running into: 1. A lot of the docs are in the Archives section, and tend to be somewhere between unhelpful and actively confusing — but there’s nothing on the pages themselves to indicate that they’ve been archived. I’ve literally taken to keeping the overall guide page open, and doing a quick command-F with the title of a page to see if it’s in the Archive section, because it’s the fastest way to be sure I’m not reading obsolete documentation! 2. The docs, especially the Archives docs, frequently fail to distinguish between Serverless Stack and Serverless Framework. For example, this page, which is in the Archives section under “Serverless Framework”, nonetheless does not have the word “Archive” or the word “Framework” anywhere on it. In fact, it’s not until halfway down the page, when it starts giving instructions on how to update

serverless.yml

, that it even begins to be clear that it’s about Serverless Framework rather than modern SST. 3. No breadcrumbs or section-based organization for the Archives pages. From a given Archives page, such as the above, there’s no way to tell what section of the guide it’s located under, other than the aforementioned “open up the table of contents and search for the page title”. It would be extremely helpful to have either or both of: a. Breadcrumbs at the top, like `Archives > Serverless Framework > Building a Serverless API > Add a list all the notes API”. b. A side nav bar that displays the guide section hierarchy, auto-expanded to the currently open page. i. Note that the current right-side nav bar does not auto-expand, does not highlight the current page, and shows up on pages (e.g. this one) that are not actually indexed from it at all. 4. Consistent use of “Serverless Stack”/“SST” and “Serverless Framework” language. a. Section titles like “BUILDING A SERVERLESS API” are actively confusing, when we are dealing with two such similarly named frameworks. b. Some pages, such as this one, are under really obscure or even misleading sections of the guide. This page is about storing secrets securely using Serverless Framework — but it’s in the “Best Practices” section of the (archived) guide, and nowhere in the section title, the other page titles, or the page itself is “Serverless Framework” explicitly mentioned. 5. The “Search” feature on docs.serverless-stack.com appears to only search the v1 constructs, even if one is currently on a v0 constructs page. This makes the search function effectively useless for those of us who are on v0. I understand that this is a “me problem” — but it would be great if the search function were context-aware, or at least offered the v0 search results (appropriately tagged) rather than suppressing them. 6. It would be great if all of the v0 constructs pages had the same warning at the top that the main “v0 Constructs” has (i.e., “_CAUTION This is the SST v0.x Constructs doc. SST v1 is now released. If you are using v1, see the v1 Constructs doc. If you are looking to upgrade to v1, check out the migration steps._“). It would help people who accidentally ended up in the wrong version to figure out what had happened to them. Without that header, it’s really easy not to notice that the URL has changed from “…constructs/v0/Api” to “…constructs/Api” or vice versa.

pretty much my thoughts too, could not agree more

I completely agree

@mickey phoenix This is pretty helpful! For the guide part of it, do you think a lot of this would be solved with a breadcrumb navigation that showed that a chapter was a part of the archives? Or should each of the archived chapters have a little banner at the top as well. Also I'm curious how you are ending up on the archived chapters. Are you landing there through the site search?

6. It would be great if all of the v0 constructs pages had the same warning at the top that the main “v0 Constructs”

Added