diff --git a/handbook/company/why-this-way.md b/handbook/company/why-this-way.md index d363e5e01e..010680a7b3 100644 --- a/handbook/company/why-this-way.md +++ b/handbook/company/why-this-way.md @@ -131,7 +131,7 @@ Besides the exceptions above, Fleet does not use any other repositories. Other ## Why not continuously generate REST API reference docs from javadoc-style code comments? Here are a few of the drawbacks that we have experienced when generating docs via tools like Swagger or OpenAPI, and some of the advantages of doing it by hand with Markdown. -- Markdown gives us more control over how the docs are compiled, what annotations we can include, and how we present the information to the end-user. +- Markdown gives us more control over how the docs are compiled, what annotations we can include, and how we [present the information to the end-user](https://x.com/wesleytodd/status/1769810305448616185?s=46&t=4_cwTxqV5IXDLBvCm8KI6Q). - Markdown is more accessible. Anyone can edit Fleet's docs directly from our website without needing coding experience. - A single Markdown file reduces the amount of surface area to manage that comes from spreading code comments across multiple files throughout the codebase. (see ["Why do we use one repo?"](#why-do-we-use-one-repo)). - Autogenerated docs can become just as outdated as handmade docs, except since they are siloed, they require more skills to edit.