Discussion: improving the developer onboarding documentation

[niklasdewally]

The aim of this issue is to discuss how to improve the VIP onboarding documentation (currently on Github Wiki).

I have been thinking of how we could use the wiki more effectively. Maybe we can extract a pdf of the entire contents as a "book" and we all aim to make sure that is as complete as possible. This project is a good example: https://github.com/jobisoft/wikidoc

Could be a project for someone next semester...

Originally posted by @ozgurakgun in #393 (comment)

[ozgurakgun]

Thanks @niklasdewally - very interested in hearing opinions on this.

Onboarding is definitely an important aspect. I am hoping this can also evolve into a textbook of sorts (over time) that covers modelling in Essence and documenting how we target multiple solving paradigms.

When I say it can be a project, the general project management / product ownership would be someone's project whilst everyone would be expected to contribute to the content.

tagging all @conjure-cp/vip-students

[ozgurakgun]

also, to add: there is a lot of existing content, examples, notebooks, demos so we are definitely not starting from scratch. organising these will be an important task though.

[niklasdewally]

On project management:

We could have more tracking issues for subprojects, so we can have a single place to discuss them and have a todo list for them. At the moment we just have lots of unrelated little related issues sitting around, and there might be value in grouping these.

For example, #171

If you create a task list inside an issue, you can then convert individual tasks into issues, reorder them etc. Issues in a task list show their tracking issue in the Github UI (e.g #243)

When we get some ideas for this, we should make a tracking issue to list all the related tasks we need to do for it.

[niklasdewally]

@ozgurakgun in relation to #483, where should we put user documentation for the CLI?

I see a few possibilities:

• We keep this stuff in a section in our docs site?
• We keep / generate a manpage which is automatically copied over and hosted on our docs site.
• We generate --help which is automatically copied over and hosted on our docs site.

[niklasdewally]

I ran into this earlier : https://docs.rs/clap_mangen/latest/clap_mangen/, which could do much of the work for us. However, it could run into the same limitations around formatting text that I had in #483