Improve docs

[marcin-rzeznicki]

There are several things that the documentation is currently missing and could be helpful to future contributors:

• Explain code organization
• How to test your code
• How to debug
• ...

It can be added in form of CONTRIBUTING guide

[luksow]

Some new features are still not described.

Also it'd be good to have a docs page beside README.

[rpiotrow]

README mentions CaseClass1Rep which is not explained (and it is specific for kebs). IMHO, it should be described and explained how it is used in kebs.

[rpiotrow]

If we would like to use GitHub Pages for it, we can use:

• mdoc - that can process markdown files into markdown files, benefits:
  • it has ability to compile sample code scala
  • checks internal links
  • it support some kind of variables (e.g. we can "inject" value of current version of the library)
• for creating site from markdown (either "raw" one or output from mdoc) we can use:
  • jekyll
    • default mechanism of GitHub Pages, pretty old, but looks mature
  • docusaurus
    • downside: for what is see it has only option to creates website on a separate branch (gh-pages)
    • upside: mdoc suggested library
    • upside: modern stack

Probably we will need to move documentation from the README.md in the root directory into some structure of files. Current README can contain some overal description with list of features - which will link to the documentation on the GitHub pages.

I would suggest to try mdoc and jekyll and see how it looks. We can create fork of the repo and experiment there to not litter main repo, what do you think?