Write a policy/guideline section related to (technical) documentation

[ghost]

Good technical online documentation is critical to a successful and useful open-source project as it's often the first entry point for both users and potential contributors. While it's definitely out of scope of the CEH to prescribe the content of documentation and general strategy for documenting a given project, providing guidelines on where and how documentation should be published seems helpful.

Furthermore, each particular project lives in relationship with other parts of the whole Cardano ecosystem so the question of providing some form of entry-point or directory for newcomers might be worthwhile to address as part of this policy.

Here is a (probably incomplete) list of various technical documentation sources I am aware of:

• https://docs.cardano.org: Maintained by IOG, provides high-level documentation about various parts of cardano but is also an entrypoint into specific projects' documentation
• https://developers.cardano.org: Maintained by the CF, aims at providing comprehensive resources for developers building on Cardano
• https://hydra.family, https://marlowe-finance.io/ and https://mithril.network : Examples of single projects' integrated documentation website containing various documents, ranging from the very technical to high-level use cases, through links to tools and playgrounds
• https://plutus.readthedocs.io/en/latest/ or https://plutus-apps.readthedocs.io/en/latest/: Examples of projects publishing documentation (mostly tutorials/guides, but technical focus) to readthedocs.io
• https://input-output-hk.github.io/cardano-node-tests/: Publishing documentation as Github pages within an org
• https://input-output-hk.github.io/ouroboros-network/: Publishing only Haddock documentation as Github pages
• Documentation provided as PDFs like the Shelley ledger specification or the Network design document, usually built in CI

I have some opinions on where to go but would be interested in having other people's feedback and advices on this.

[JaredCorduan]

Would the table at the top of the ledger repository, which links to a lot of ledger documentation, be a good candidate for this list?

[ghost]

Good catch, updated the description

[michaelpj]

I'm not sure quite what you're imagining as a policy? If we have a canonical documentation strategy then yes, we can prescribe that people follow it, but it's unclear to me whether we do.

Or to put it another way: in the spirit of having the policy follow existing behaviour rather than trying to coerce behaviour through policy, I think we need to first of all get people doing something consistent before we can codify it 🤔

Other than that I'm not sure what we could say? We could say that projects should link to all known (and approved of?) locations that provide documentation on that project?

[ghost]

The policy part should probably be only about how a Cardano project would be "discoverable" or linked from some top-level portals. Then we could have a practice section describing various possible approaches we find in the wild to publish documentation.

[michaelpj]

Okay great, that sounds doable, if we can pin down what "discoverable" means!

[ghost]

That's why I am invoking docs.cardano.org and developers.cardano.org :)

[olgahryniuk]

A couple of thoughts from the tech writers' perspective.
Since IOG is currently maintaining docs.cardano.org, it would be amazing for it to be the entry point for other technical docs related to Cardano. Depending on the chosen plan (whether we link to other documentation or find a way to reflect the contents of various directories), we'd love Cardano Docs to serve this purpose.
In line with that, the idea of having the policy sounds great. This way, all the projects can adhere to a certain 'standard' and the docs would be consistent. If there is any way we (tech writers) can help with this, please let us know.

[ghost]

Providing your insights and suggestions here is a great way to contribute :)

[olgahryniuk]

In general, every project has its own dedicated repository and multiple folders, where one contains documentation specifically.
In my opinion, it's great to have all the structure outlined in the main readme file. For example, a certain Cardano component (like node, ledger, consensus, networking, etc) can provide the following details:

• What is it and why is it needed?
• Who is it for?
• What needs/challenges does this component address?
• What are the main features (if there are any)
• Documentation: the main readme file can just link to it, but it's good to provide some details. For example:
  • Getting started: some high-level overview > link
  • Other main sections: overview > link
• Technical details that are essential for every project. How it works.

[ch1bo]

Having some guidelines on how to maintain domains and also availability, links between & longevity of documentation come to mind. Especially as the PDF links went down also in this description (as a fun fact).