Docs required

[pshirshov]

We need to better document the internals of the library, the design decisions we made and trade-offs and limitations we had to deal with.

This should allow potential contributors to quicker get onto the board.

[sibrash4]

Hi! I'm interested in this bounty and wanted to check if it's still open. If so, I'd love to get more details to see if it's something I can take on.

1. Scope: What parts of the docs need the most work? Are we focusing on internals like design decisions and trade-offs, or more on user guides and examples?

2. Tools: Are we sticking with the current setup, or is there any interest in switching to something like Docusaurus, MkDocs, or GitBook?

Let me know — looking forward to your thoughts!

[pshirshov]

I would advise against taking this issue. This is not about usage examples (which are trivial in case of this library).

We need to describe how the library works, which decisions were made and why, what was sacrificed and why.

In order to deliver, you will need to have deep understanding of the library internals and history, that would require a substantial amount of effort.

@jdegoes I've opened this issue as a reminder for myself to eventually turn my thoughts into notes which would be useful for others, may I ask you to remove the bounty please?

For future reference, I've briefly described the problem here: https://www.youtube.com/watch?v=ShRfzVz58OY , but that's not enough.