We could improve the documentation of the library

[esuca]

These days I've been thinking about giving a twist to the documentation:

Archimedes-js is a library built by developers for developers and I think we could improve the developer experience by having even better documentation.

I was thinking about adding TSDoc documentation to all public archimedes APIs. By doing this we could look at the documentation for that method using the IDE, for more advanced cases we can go to the official documentation page as before.

And looking at the documentation page it is like a WIP page, we don't have the JVM part finished and the JS part is basically just the Archimedes page. The page has potential but in my opinion by having it like that we are giving a bad impression.

Do we really need a documentation page? I think I'm asking this question late, but....

The README file is most of the time the first contact with the library, we could add there the installation step, the arch part explaining the commands and queries, and a page for each link we have.
We could also add a FAQ part with questions like How to create a custom link?

I think these changes make the library documentation more visible and easier to use as developers and also gives a better first impression of the library.

What do you think?

[kemilbeltre]

I think it is important that a library is well documented.

Two things to consider:

1. Documentation: For developers that are interested to learn how to use it, from the point of view of someone who doesn't even have a high level of programming skills.

2. README: for those who want to start quick or contribute.

[cesalberca]

1. I agree, there is room for improvement in this area for sure. Maybe it could be interesting to create a guide with an example project.
2. The contributing section is linked in the README and it's located here: https://github.com/archimedes-projects/archimedes-js/blob/main/CONTRIBUTING.md

[cesalberca]

I'm going to reach out in order have some basic documentation of the JVM part. Adding ts-doc is something I was hoping to integrate in the future. Maybe we should start looking at that now. I've found that TypeDoc can be used. Right now there is a plugin for TypeDoc with Docusaurus 2 that we could use to generate API documentation. What do you think @esuca?

[esuca]

I don't know if TypeDoc is the right choice here. For me the most important part of the documentation is to be able to open it from the IDE and TypeDoc seems to struggle with that. Take a look here.

I would like to help with the documentation writing, maybe by the end of December I will have more free time.