2 Commits

Author	SHA1	Message	Date
Thomas Heartman	d5fbd0b743	refactor: move docs into new structure / fix links for SEO (#2416) ... ## What This (admittedly massive) PR updates the "physical" documentation structure and fixes url inconsistencies and SEO problems reported by marketing. The main points are: - remove or move directories : advanced, user_guide, deploy, api - move the files contained within to the appropriate one of topics, how-to, tutorials, or reference - update internal doc links and product links to the content - create client-side redirects for all the urls that have changed. A number of the files have been renamed in small ways to better match their url and to make them easier to find. Additionally, the top-level api directory has been moved to /reference/api/legacy/unleash (see the discussion points section for more on this). ## Why When moving our doc structure to diataxis a while back, we left the "physical' files lying where they were, because it didn't matter much to the new structure. However, that did introduce some inconsistencies with where you place docs and how we organize them. There's also the discrepancies in whether urls us underscores or hyphens (which isn't necessarily the same as their file name), which has been annoying me for a while, but now has also been raised by marketing as an issue in terms of SEO. ## Discussion points The old, hand-written API docs have been moved from /api to /reference/api/legacy/unleash. There _is_ a /reference/api/unleash directory, but this is being populated by the OpenAPI plugin, and mixing those could only cause trouble. However, I'm unsure about putting /legacy/ in the title, because the API isn't legacy, the docs are. Maybe we could use another path? Like /old-docs/ or something? I'd appreciate some input on this.	2022-11-22 09:05:30 +00:00
Thomas Heartman	0e3e725a17	docs: add "The Anatomy of Unleash" (#2138) ... ## What This PR 1. adds a new topic document, "The Anatomy of Unleash", which explains how Unleash is built up as a system. 2. It also moves the "topic guides" sidebar entry from position 4 to position 2. 3. Finally, it introduces a new `Figure` component for the documentation, to be used with images that should be shown with captions. ## Why Referring to the same numbers as mentioned above, here's some background for these changes: 1. We have gotten requests from enterprise users for a way to help new Unleash users understand the system. Together with customer success and customer journey, we agreed that an explanatory guide would be suitable. It aims to give the reader an introduction into what pieces constitute the Unleash system. 2. As part of a discussion, it was suggested to move topic guides higher up to make them more visible. There's a few reasons for this: 1. New users of Unleash should be able to keep reading about Unleash after the basic introductory material. When left at the bottom, topic guides are often overlooked 2. As a justification, it was proposed that reference docs are often the last thing you look for, so it makes sense to put that last. 3. Thinking about a new user's flow, it also makes some sense: first read introductory material, then dive deeper into what Unleash is and what you can use it for, then look for how-to guides if you're stuck, and finally consult the reference material for later. 3. These diagrams aren't necessarily very self-explanatory, so adding a caption makes a lot of sense. We didn't have a component from this previously, so I added one. Co-authored-by: NicolaeUnleash <103567375+NicolaeUnleash@users.noreply.github.com> Co-authored-by: Simon Hornby <liquidwicked64@gmail.com> ## Commits * docs: add raw export of anatomy document * docs: move the topic guides section to near top of sidebar * docs: add inter-doc links, some reformatting * docs: fix broken links * docs: add a Figure element for figures with captions * docs: add more styling to figures * docs: align on styles * Fix: add fuller figure caption * docs: rephrase heading * Docs(test): try new way of importing images * Docs(test): images take 3 * docs: Convert all images to using the figure component * docs: add projects to list of top-level resources * docs: add captions for all figures. * docs: reorder images * Docs(fix): typo: extra brackets * Docs(style): remove box shadows and border on fig caption images * Docs(chore): remove commented-out css * Docs(refactor): use css variable for small font size. To facilitate reusability and convey meaning. * docs: rename anatomy doc * docs: add note about strategies vs constraints * Updating the images * Apply suggestions from code review Co-authored-by: Simon Hornby <liquidwicked64@gmail.com> * Update website/docs/topics/the-anatomy-of-unleash.mdx * Docs(fix): remove redundant comma * docs: add link to node js sdk * docs: mention that a toggle must be active in an env to be enabled * docs: add note about environments and api keys * Docs(reword): swap dev and prod in example * docs: fix typo in the image * docs: make figures in text full-width * docs: move environments and API keys call-out to after figure * docs: add borders to figures * docs: add image float css idea * Revert "docs: add image float css idea" This reverts commit 69f27d304b. Co-authored-by: NicolaeUnleash <103567375+NicolaeUnleash@users.noreply.github.com> Co-authored-by: Simon Hornby <liquidwicked64@gmail.com>	2022-10-19 13:14:49 +02:00