Move content from SDK docs to new "Reference" docs section

[Reccetech]

Problem

This is a proposal to create a new "References" doc section. Within that section we will move over the bulk of the content from the SDK and API docs into these new Reference docs. For example on a page like here we would move everything except the code samples into the Reference docs.

At a higher level the philosophy of the contents of the reference docs will be: Reference docs contains propositional or theoretical knowledge that a user looks to in their work. The only purpose of a reference guide is to describe, as succinctly as possible, and in an orderly way. Whereas the content of tutorials and how-to guides are led by needs of the user, reference material is led by the product it describes. In the case of software, reference guides describe the software itself - APIs, classes, functions and so on - and how to use them.
Source here

In contrast the SDK docs will contain guides on how to install the SDK, and guidelines on how to use the SDK functions in alignment with the reference docs. This can include code snippets and tutorials.

Feedback appreciated.

Solution

See above.

Alternatives

No response

[olsentorfinn]

I personally find these kinds of documents invaluable specifically the systems architecture style of descriptions regarding how APIs work and maps of classes/functions etc. I feel like the best docs sections I've seen all do this really well. Got my vote.

[bguiz]

💯 we have needed to do this for a long time!

[bguiz]

The main implementation challenge is going to be converting the docs formats of different parts of the various interfaces that developer facing into a coherent-looking format.

• For the SDKs, we'll have esdoc or jsdoc + godoc + javadoc + ... etc
• For the APIs, we'll have OpenAPI (for Mirror Node APIs) + TBD format (for JSON-RPC 2.0) + TBD format (for HAPI protobufs) + ... etc

[bguiz]

Once the conversion/ collation is done, the next challenge will be converting/ rendering it into something that we can use and render within docs.hedera.com (which uses Gitbook).

Considerations:

• Does Gitbook support this functionality?
• Should we continue using Gitbook or look for alternatives as a result?
• Should we consider an intermediate solution where we render the reference docs in a separate subdomain from the main docs in the interim period while we resolve both the collation and conversion implementation tasks?

[Reccetech]

So an interesting example we can look at is the XRP docs here If you go down on this page you'll see they have well documented "XRP Ledger Protocol Reference". This is what I am proposing to create. If you click through their SDKs you'll see various types of docs probably depending on who built it and the developer need of that community. So the Python docs is a pretty comprehensive Wikipage. The JS and Java are self generating docs. So we would need to make a decision on what the SDK docs look like and their contents.