About the tutorial and the documentation in general

General
1

The tutorial “assumes you have completed the steps in Getting Started and can connect to Datomic Cloud”.

But more importantly, it actually assumes you already created a database to be used by the tutorial.

I recommend to include the instructions of creating the database, to make the tutorial a bit more independent.

And finally, hire a documentarian and connect with https://www.writethedocs.org/

2

… In the Programming with data section there is a paragraph that says:

Let’s put the types and sizes into the database and define a collection of colors we already added:

But the code is:

(def types [:shirt :pants :dress :hat])
(def colors [:red :green :blue :yellow])
(d/transact conn {:tx-data (make-idents sizes)})
(d/transact conn {:tx-data (make-idents types)})

Technically speaking it is correct because you are adding sizes and types. But the first 2 lines are defining types and colors, when it should have been:

(def sizes [:small :medium :large :xlarge])
(def types [:shirt :pants :dress :hat])

…
[update]
So the reason was that the expression (def colors ...) was not instructed before. So yes, the document is technically correct (“more correct” than what I described), but it could be probably reordered so the code snippets have instructions more cohesive between them: like mixing (def types ...) (def sizes ..) with (transact ... types) (transact ... sizes) instead of types and colors with sizes and types.

It seems silly, but it could help the novice reader (audience for a tutorial).

3

The Try It[1] part of the section Querying the Database refers the lambda function as items-by-type:

aws lambda invoke --function-name $(GROUP)-items-by-type --payload \"hat\" /dev/stdout

But the code I just cloned for the tutorial doesn’t have that lambda function.

In any case, it has get-items-by-type[2] lambda function.

[1] THE DOCS PAGE OF DATOMIC /cloud/ions/ions-tutorial.html#orgf6b6d18
[2] THE GITHUB PAGE /Datomic/ion-starter/blob/efc93063578719ce5d754e0e960bfc4b7c94b0af/resources/datomic/ion-config-sample.edn#L16

4

Thanks for catching those.
We’ve updated/fixed the relevant sections of the docs.

1 Like