Conversation
Changed "intro" to "quickstart", added redirect Made "Getting started" area only about getting started, for new users Made new "Essentials" and "Developer tools" areas for other things Made some links that opened a new tab, not open a new tab
There was a problem hiding this comment.
Pull request overview
This PR refactors the top-of-sidebar information architecture to keep “Getting Started” focused on onboarding, while moving broader material into new “Essentials” and “Developer Tools” sections and updating relevant internal links/redirects.
Changes:
- Renames “Introduction” to “Quickstart” and adds a redirect from
/docs/getting-started/introto/docs/getting-started/quickstart. - Reorganizes
docs.jsonnavigation groups (new “Essentials” and “Developer Tools”, and reorders “Guides”/“Cookbook” under “Learning & How Tos”). - Updates the translation beginner guide to use internal
/api-reference/...links, and adds it as a recommended next step in Quickstart.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| docs/learning-how-tos/examples-and-guides/translation-beginners-guide.mdx | Switches several API reference links from external to internal /api-reference/... routes. |
| docs/getting-started/quickstart.mdx | Updates page title to “Quickstart” and adds a link to the translation beginner guide in the “quick steps” list. |
| docs.json | Restructures sidebar groups and adds the /docs/getting-started/intro → /docs/getting-started/quickstart redirect. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
docs.json
Outdated
| "docs/getting-started/intro", | ||
| "docs/getting-started/about", | ||
| "docs/getting-started/quickstart", | ||
| "docs/getting-started/client-libraries", |
There was a problem hiding this comment.
The client libraries page should be in the developer tools section
There was a problem hiding this comment.
I don't agree. Right now it's not easy to learn anything about our client libraries on this site, unless you happen to be one of the intro pages. It's not great that people have to navigate to github to learn how to use them, but at least a persistent sidebar link makes them discoverable. For the great majority of developers, finding info on their client library is also an essential part of getting started.
There was a problem hiding this comment.
The page lives under Getting Started, which implies tutorial/onboarding content. But this is pure reference (a catalog of libraries). Users in "getting started" mode expect guidance on which library to pick and how to install it — they get a link list instead.
Recommendation: Move this page to Developer Tools, and add a how-to guide ("How to install a DeepL client library") to this section that includes installation commands for each language.
There was a problem hiding this comment.
I like your idea in the abstract... but I don't think people need a guide for how to install each client library. There's not much to say! These instructions are already in the github repos, and I think that's a logical place for them.
On the other hand, I agree that this page is not very getting-started-y as it stands. Beginners won't need to know about out-of-the-box retries etc.
How about this: I could start this off with a couple of paragraphs explaining about what the client libraries are, what they do, where to find documentation and examples. There wouldn't be much. I think the link boxes are still useful. We could then remove/rewrite the "features include" area or put it elsewhere. The rest could be in a "see also" area.
The page didn't provide additional value beyond the quickstart. Adds a redirect from its URL to the quickstart page and removes references from the sidebar, quickstart, and CLI pages. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* moved existing client libraries page back to "Developer Tools" * wrote new client libraries page suitable for "Getting Started" section * Since "About" is now the home page, moved our banner there, and tweaked the vertical margins to avoid extra unsightly blank space
|
Ok, I've done a few things here:
I'm not convinced this is the best path. There's not much content in the previous client libraries page aside from the links, but I've preserved this info so we have something for the "Developer Tools" page. Arguably we don't need this page. I'm also not convinced that our present "About" page should be the first page in the "Getting Started" section, but if we have this page, it makes sense to have it first. Logically this should be rewritten, but I'm trying to avoid too much scope creep. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (1)
docs/getting-started/quickstart.mdx:5
quickstart.mdxfrontmatter no longer includes adescription. In this section, every otherpublic: truepage underdocs/getting-started/includes a description (used for SEO/search/snippet text), so Quickstart should keep one as well to avoid an empty/less-informative page summary.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @@ -0,0 +1,45 @@ | |||
| --- | |||
| title: "Client libraries" | |||
There was a problem hiding this comment.
This new page is public: true but has no description, and its title is identical to docs/getting-started/client-libraries.mdx. In the sidebar this will likely show two indistinguishable “Client libraries” entries; consider adding a description and a disambiguating sidebarTitle/title (e.g., “Client libraries (reference)”).
| title: "Client libraries" | |
| title: "Client libraries" | |
| sidebarTitle: "Client libraries (reference)" | |
| description: "Reference page for DeepL official client libraries, the CLI, and community-created libraries." |
There was a problem hiding this comment.
good point Copilot...
We've long known the "Getting started" area is too big , and contains many items that are not about just getting started with the API. People tend to add new docs entries to this area because we all want our new content to be at the top - but it can't all be at the top. I moved a few items down some time ago, and now the area has once again grown bloated.
A few of us have long wanted to at least divide this area into two sections. So, here's what I did:
And a bonus:
I'm not sure about the word "Essentials", but it's the best I could think of. Claude's suggestions were worse.
I wasn't sure we wanted a "Developer tools" section with two items, but when I added this, I thought it looked quite nice, so I kept it.
Comments and improvements desired! I'll let this change marinate until at least after Easter holidays, so folks have a chance to notice it.