thenbe
commented
1 year ago One option we have for documenting API options is the use of tools like typedoc, docs-ts, etc. The main reason they appeal to me is that they unlock the ability to use a single source of truth* for both:
a. intellisense
- (for consumers) there when you most need it as you're trying to discover the API
- (for contributors) shows up as they're actively working on the codebase, encouraging them to keep the docs updated as they submit PRs
b. external documentation
- linked from the project's landing page + README. A simple way for devs who've yet to decide that the library meets their needs to view any available options.
The only thing to watch out for when setting one of these tools up would be to use the available config/flags to only expose documentation for the public API types, keeping the generated docs nice, simple, and free from bloat. I've never configured one of these before, but I've been on the consuming end and some can become unwieldy. Although, most of the time this is only relevant for projects with a large API surface area.
* The source of truth is JSDOC-style comments like this, which are then used to create documentation like so.
The API surface isn’t very well documented outside of a few common use cases that are listed on the website. As this library grows, we need better docs.
We could either do Docusaurus or bake in docs in the current website.
Further, it might also be nice to have a Discord channel for this package. A server doesn't make sense since this isn’t a framework—perhaps we can integrate into one of the existing Svelte community Discord servers?