Documentation improvements

[skeet70]

We got this question on Discord:

The attached screenshot is taken from the “pinecone-semantic-search.ipynb”, and I assume that, in production, this portion of the code needs to be edited to configure the encryption for ourselves, is that right? I have questions about what some of these things are, such as “RotabtableSecret”, “StandardSecretes” and “StandaloneSecrete”, and haven’t found much descriptive information yet. I wonder if you could explain them or point me to where I could read about them.
Also, for generating the key_bytes, do you have any suggestions on how it should be done in Python? I am wondering if you have any recommended libraries or functions?

We have some high level documentation coverage on docs.ironcorelabs.com and some very low level, low context, in-library documentation. What this question shows is that we're missing some of the connective tissue, so someone can understand how to go from the examples to a production setup (for both Standard and SaaS Shield modes). What do the different secret types mean? How does one go about rotation? Why is there a list of StandardSecrets, and should they be rotating those? What sources of randomness are acceptable for cryptographic use? etc

[coltfred]

Timebox this to a 5 and make as many improvements as we can.