[FR] - Better documentation for cardano-cli outputs

[gitmachtl]

If you're deep in the code and involved in every new feature/change about cardano-cli, than this might not be an issue. But, for developers that are not that involved or that are new to cardano, its sometimes a bit of a pain to do a proper interpretation of certain cardano-cli query outputs.

I am not talking about the basic outputs like a utxo query or a stake-address-info query, those json outputs are well documented with there key naming schema alone imo.

When it comes to outputs like governance action queries, than its going to be more difficult. Let me give you an example:

 [
   null,
   [],
   {
   "keyHash-5f1b4429fe3bda963a7b70ab81135112a785afcf55ccd695b122e794": 379,
   "keyHash-9393c87a66b1f7dd4f9b486a49232de92e39e18b3b20ac4a539b4df2": 379
   },
   {
   "denominator": 7, 
   "numerator": 4
   }
]

If you are new to such an output you may wonder "whats the null entry?" or "whats the empty array" or "whats the number behind the keyHash entries"... etc. Btw, that object with denominator and numerator can also change to just a decimal number, if it has a finite number of decimals 😱 So, two different outputs for the same thing. Its not an issue, if documented!

Or for example:

[
   [
      [
         {
         "credential": {
         "keyHash": "c13582aec9a44fcc6d984be003c5058c660e1d2ff1370fd8b49ba73f"
         },
         "network": "Testnet"
         },
         1234567890
      ]
   ],
   null
]

Yes you can read out some basic infos, but there are 3 cascaded arrays. So, which one can actually hold more than one treasury withdrawal request? Can there even be more entries in an array or is it always just one?

As you can see, there are many of those.

This issue is not about changing the output! That is currently out of scope imo, because it would be too many breaking changes for 3rd party tools.

Its ok that the data output looks like it does, saving space and not having key/value pairs on every entry. But it lacks documentation. 😞

So, the intention of this gh issue is to raise awareness to somehow provide better documentation for existing and new developers and users in general.

It would be nice to have such a documentation on a website in a normal text form, or PDF, or similar.

Also it would be nice to have such a documentation like those familiar REST API documentation sites, where you can see all available commands and there outputs (maybe driven by goldentest sources?) via a TRY button or so. Developers are very familiar with such sites and they like them.

The documentation should of course cover every cardano-cli output, not just governance related ones like use in the examples.

Ok, this was just a quick first entry to raise this issue. Looking forwards to the discussions. 😃

[carbolymer]

Related issue to CLI output: #566