Tidy cocli documentation

[yogeshbdeshpande]

Refactor cocli documentation for better expression. Fixes #102

[thomas-fossati]

I don't believe that splitting the existing content into separate files will effectively address the issues identified by @hannestschofenig.

The points he made were:

1. Increase the veracity of the command line examples by using the template files from the data/templates folder
2. Give the reader an early overview of the CoRIM flow and explain how each cocli sub-command fits into the flow
3. Link the template files from the examples so that the user can inspect them with a single click

which this PR doesn't seem to address.

[yogeshbdeshpande]

3. m the examples so that the user can inspect them with a single

1. This is just a start: It does not make sense to have a long README.md like this. Users get lost:

2. Yes for your point 1, I am going to make a follow up PR. It will use the actual templates from the Templates folder, in the README examples!

3. Linking the Template files in the examples, yes, we can do it!

This is a start and believe it is a good start!

[yogeshbdeshpande]

2. overview of the CoRIM flow and explain how each cocli sub-command fits i

• Also I observed Hannes could not locate some of the cots documentation

[yogeshbdeshpande]

2. Give the reader an early overview of the CoRIM flow and explain how each cocli sub-command fits into the flow

Also on 2. above, is helped by splitting README.md as Reader gets much more quicker access to overall flow daigram, which sets the real context!

[thomas-fossati]

It does not make sense to have a long README.md like this. Users get lost:

No one lamented on the length of the file. I think you are solving a non-issue here. The main concerns were:

• the relative positioning of the material, with the "overall picture" stashed at the bottom rather than near the top

• the lack of veracity of the examples

See also #102

2. Yes for your point 1, I am going to make a follow up PR. It will use the actual templates from the Templates folder, in the README examples!
3. Linking the Template files in the examples, yes, we can do it!

Why not address it now rather than doing a split that no one asked?

[yogeshbdeshpande]

It does not make sense to have a long README.md like this. Users get lost:

No one lamented on the length of the file. I think you are solving a non-issue here. The main concerns were:

• the relative positioning of the material, with the "overall picture" stashed at the bottom rather than near the top
• the lack of veracity of the examples

See also #102

2. Yes for your point 1, I am going to make a follow up PR. It will use the actual templates from the Templates folder, in the README examples!
3. Linking the Template files in the examples, yes, we can do it!

Why not address it now rather than doing a split that no one asked?

Yes, I am making the change to replace the fictitious examples with real examples, as part of the same PR:

However, at the same time long README's are not preferred. They can be problematic, risk reader losing context!

[yogeshbdeshpande]

@thomas-fossati Not sure whether you noticed the point mentioned in #89

I am also trying to address this issue, using the same PR

[thomas-fossati]

@thomas-fossati Not sure whether you noticed the point mentioned in #89

I am also trying to address this issue, using the same PR

Yes. I'd have expected that this PR would move up that diagram, make the command line examples replayable using existing templates, and link those templates at the point where they are used.

Instead, it mainly consisted of fixing something that no one had complained about 😄

[yogeshbdeshpande]

@thomas-fossati Not sure whether you noticed the point mentioned in #89
I am also trying to address this issue, using the same PR

Yes. I'd have expected that this PR would move up that diagram, make the command line examples replayable using existing templates, and link those templates at the point where they are used.

Instead, it mainly consisted of fixing something that no one had complained about 😄

Yes, the diagram is much closer now, as the README.md is nicely into seperate sub-sections, per context. A user does not has to browse all the way down to view the picture.

We can move this right at the top, only risk I feel is displaying something without much context!

[thomas-fossati]

thanks very much for incorporating my comments!