Elgato_dark/fleet
1
0
Fork 0
mirror of https://github.com/fleetdm/fleet synced 2026-05-23 17:08:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 83

Add link to "Why not continuously generate REST API reference docs fr… (#17879)

Browse source
This commit is contained in:
Sam Pfluger 2024-03-27 03:12:53 -05:00 committed by GitHub
parent d28810a8f2
commit 1261956a89
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 1 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
handbook/company/why-this-way.md
View file

@ -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.