Better documentation?

[KillyMXI]

Readme, as it is now, is not really convenient to quickly grasp the available methods and functions and quickly access the needed ones.

I understand it is desirable to have everything readily available right in the Readme both at GitHub and NPM, but after certain point it becomes really difficult to use. Better formatting might help to some extent, but it becomes harder to maintain.
Therefore I suggest to leave a handful of examples in the readme, to get a taste of the lib, and move the API details to more appropriate location.

For a library with a rich set of entities I expect to see a documentation page/site with a sidebar listing all of them and a detail view providing description and examples for a single entity.

If something like this already exists - I can't find it without a link on a visible place at the repository front page.

If it doesn't exist - consider creating it.
With GitHub Pages or GitHub Wiki or Read the Docs for example.

[francisrstokes]

Hey @KillyMXI, thanks for opening an issue.

I think you make a good point - the project has grown quite a bit, and the readme isn't really doing it justice at the moment. A dedicated documentation site hosted on github pages would probably fit nicely.

A good path forward could be:

• Add documentation in the form of JSDoc to the code
• Introduce a (simple) build step, that builds the documentation based on the JSDoc comments, and strips the comments from the main code
• Set up github actions to automatically build and deploy whenever the master branch is updated.

[Nitwel]

My plan for improving the documentation would be the following:

1. Split up the documentation into the following 4 segments explained here: https://documentation.divio.com/
2. Use https://github.com/TypeStrong/typedoc and JSDocs for generating reference documentation and deploy it with github pages
3. Build upon the current documentation to support those 4 types of docs.

Thoughts @francisrstokes ?

[KillyMXI]

I see there is an ongoing work to migrate to TypeScript.
In that case https://tsdoc.org/ might be a preferable option compared to JSDoc.