Users can find documentation/tutorials on Crux

[jarohen]

from @dgr on #747:

As a new Crux user, I've spent a lot of time reading and re-reading the docs. The following are some suggestions for improvements to the documentation that I believe will make Crux more easily understood by new users.

1. DONE (see Docs changes #822) An overview of the high-level programming concepts from an API point of view. The current documentation spends time discussing bi-temporality, which is great, but doesn't discuss things like what the node and db concepts are abstracting. You can sort of piece it together from the names, the raw API, and looking at the code, but it would be useful to just have this documented. For instance, when you start a node, what is that doing under the hood? What does a node contain once it has started? When you execute (crux/db node), what is the result of that? What is a DB, exactly? How long can I hold onto it? Why would I want to (or not want to)?

2. An overview of how Crux works architecturally and how the abstract architecture maps to each of the various deployment models. For instance, if I'm using the standalone, Kafka, or JDBC topologies, which component is performing which tasks? How does the data flow between the various components in the architecture? Where is it stored? Where is it indexed? When a query happens, which node is running that code?

3. Scaling and performance notes. It would be good to understand where the pinch-points in the architecture are and how to work around them. How does Kafka perform versus standalone or JDBC? How much effect does memory have on a node? How much effect does CPU speed have on a node? When should I scale out and add more nodes versus scaling up the nodes I have? Are there any limits to the architecture? Is there any place where the Crux team would say, "Crux is not suited for that type of application or use case" ?

[danmason]

The general order of the docs, as it stands, is somewhat obtuse and confusing, so we should consider moving things around as we extend the docs.

• Require a general pass over all sections, removing unnecessary parts and small extensions where needed. (The docs have been checked over, and cleaned up. #468)

Areas which require better documentation (card up):

• Snapshots. What are they? What are they for? Examples of snapshots. (Documentation for queries has been tidied up and extended #470) (Added an example usage)
• Examples of history api. (Documentation for queries has been tidied up and extended #470)
• TxLog, and its' uses.
• HTTP servers/remote API nodes need general better documentation, better examples/mentioning CORS. (HTTP Server/Remote API nodes need to be properly documented #471)
• Configuring rocksdb settings. (There should be documentation on setting RocksDB options #472)
• Crux CLI - unsure if it needs documenting/what's currently there.
• Improvements to the query section (Documentation for queries has been tidied up and extended #470)
• Benchmarks/performance (requiring work done on the area)

Wherever possible, should be examples available for Java and REST added.

[jonpither]

👍 Good if we can progress, find a way to eventually close #177 also

[danmason]

May be worth going through that card as a collective, seeing what is and isn't still relevant.

[jarohen]

from @refset:

• pick a style and assess priorities https://jacobian.org/2009/nov/10/what-to-write/

[jarohen]

re transaction operation reference section - see #997