Documentation Wishlist

[Benjmhart]

Over recent discussions, we've had attendance from Joseph Fajen, a technical writer at IOG, who requested topics for upcoming documentation focus. I've run a recent poll among my developers, and these were the most requested items:

Ideally, this short list can be something we add to incrementally

• A field-by-field explanation of Cardano transactions, updated for each era - so that constructing a transaction by hand from scratch is easier

• a field-by-field explanation of the protocol parameters and how we've arrived at the current parameters.

[Benjmhart]

additionally, we'd like to see these areas better documented:

• stake withdrawal and stake validators

• 'phase 1 validation' - this seems to largely be ill-defined and emergent properties of serialization code.

• time on chain, specifically timeintervals

[joseph-fajen]

@Benjmhart Thanks for gathering this list of topics, it's super valuable input. I'll discuss these with team members so we can sort out how best to address them.

[Benjmhart]

• what is the recommended way for a developer to export plutusTX scripts to a flat file? (as Cbor or as UPLC)

[joseph-fajen]

Let me know if this answers that question:
https://plutus.readthedocs.io/en/latest/howtos/exporting-a-script.html

[Benjmhart]

• Ouroboros mini-protocols full specification #26 - gaps in the spec identified by @scarmuega

[Benjmhart]

Let me know if this answers that question: https://plutus.readthedocs.io/en/latest/howtos/exporting-a-script.html

Yes it does, was this pre-existing or recently added?

[Benjmhart]

Let me know if this answers that question: https://plutus.readthedocs.io/en/latest/howtos/exporting-a-script.html

Actually one thing that could be clarified is if you're going to get CBOR or a textual representation of the UPLC, both would be helpful (CBOR for building a TX, UPLC for optimization or bugfixing)

[Benjmhart]

As requested I'm going to try and fill in the usecases for the documentation requests so far

• Explanation of the transaction type
  the developer in this case is trying to do one of the following (1) Build a transaction from a language other than haskell, (2) build a transaction for the purpose of building a test.

'phase 1 validation' - this seems to largely be ill-defined and emergent properties of serialization code. also ties tightly to these usecases

• Explanation of the protocol parameters
  the developer is trying to build a private testnet - perhaps using different parameters than Cardano's mainnet - a key example was after the Alonzo hardfork, many private testnets were created so that contracts could be tested before they were optimized enough to fit in the restrictions on script size, CPU, and Memory usage. the modified testnets allowed for higher limits so that the scripts could be tested - speeding up the refactor process.

• stake withdrawal and stake validators
  a whole range of Cardano products are set to use staking validators - many projects in their first iteration wanted to use them, however due to lack of documentation were forced to avoid them.

understanding exactly how a stake withdrawal transaction should look and how to manage utxo's staked to a script in context would help dozens of companies learn how to manage the stake rewards tied to their TVL. The result? better transparency for users, a great alternative to the 'mangled address' problem, and better control over stake yields for Defi (and other verticals) in general.

• time on chain, specifically timeintervals, and how they are tied to epoch length
  Developers on Cardano often have trouble getting transactions approved within the validityRange, this can happen for a lot of different reasons: On networks that have a fast epoch length, there is a safezone validityRange you can query from the node (many are not aware of this), However ultimately the developer needs to write transaction-building code that will work in robust conditions. understanding how to get this information from the node and what it means would greatly increase developer momentum when building real-world transaction code.

[jinglescode]

Just want to highlight our work that focuses a lot on documentation and education, Mesh. Entirely open source, with live demo, and code snippets.

[joseph-fajen]

@Benjmhart, I realize lots of time has elapsed here. But here's a follow-up item I received that I wanted to pass along regarding "A field-by-field explanation of the protocol parameters and how we’ve arrived at the current parameters" -->

• https://cips.cardano.org/cips/cip9/
• https://cips.cardano.org/cips/cip28/
  Since January I have been re-assigned 100% to the Marlowe project and I haven't been attending the Developer Experience Working Group meetings for a while.

[aleeusgr]

https://forum.cardano.org/t/poor-documentation-deterred-developers/112010

[OlofBlomqvist]

Seems I am late to the party, but I think docs.cardano.org in general should be more aligned with developers.cardano.org and not only document IOG based initiatives. Reffering to everything non-IOG as "community" tools or just have them as footnotes makes those tools look "unofficial" / not fit for professional use (imo).

Submitted part 1 of this "wishlist" as a PR to the docs repo here: input-output-hk/cardano-documentation#540 (adding aiken to docs.cardano.org)

My first wish related to documentation (less "fluff" and more content around smart contracts) actually already came thru when this was merged: https://github.com/cardano-foundation/developer-portal/pull/1080/files :)

[aleeusgr]

https://developers.cardano.org/ and https://docs.cardano.org/ are two primary resources that could benefit from more contributors and staying current.