How can documentation be improved?

[vlovgr]

• Is the intent and motivation behind Ciris clear and easy to understand?
• Is there anything unclear or that could be improved in the usage guide?
• Have you found anything that could improve the contributing guide?
• What would you like to change about the release notes?
• Anything that could improve the API documentation?
• What's missing from the readme?

[marthall]

Hi @vlovgr
Love this project, and I'm adopting it to our project. However, I have some suggestions on the documentation.

The usage guides are nice, but there is quite a big gap from them to the API. I miss some example apps which ties everything together. Would it be possible to add an example somewhere in the library? Like a template.

Look forward to hear from you :)

[vlovgr]

Hi @marthall! Thanks for your feedback! I'm currently in the process of rewriting and improving the documentation, and will definitely take your input into consideration.

The usage guides are nice, but there is quite a big gap from them to the API.

Completely agree, and this is one of the reasons why I'm rewriting the documentation.

I miss some example apps which ties everything together.

The new documentation hopefully does a better job at explaining this, but I think creating a separate repository with a small example application is also a great idea.

[vlovgr]

@marthall The updated usage guide is now live at https://cir.is/docs and the release notes roughly explain what's changed: https://github.com/vlovgr/ciris/releases. The usage guide now goes into more depth, and directly links to the API documentation where relevant. Hopefully this somewhat bridges the gap between the API and the usage guide.

[marthall]

@vlovgr That's really good! Thanks for fast reply and fix 👍

I'll check it out later this week :)

[vlovgr]

@marthall there's now a small example application here: https://github.com/vlovgr/ciris-example