Update documentation

[vangheem]

• read through all the docs
• include important modules as API reference

[leplatrem]

I went through the docs (see #166) to have a better understanding of the project scope and mechanics.

Disclaimer: I am not familiar with Plone at all (apart from having shared an office with @ebrehault for years ;))

It was not very clear to me at first that the project is some sort of «framework» that you rely on to code and build domain specific applications or a ready-to-use service (e.g. like E/S). Can you (as a frond-end developer for example) use Guillotona without coding in Python?

It might come from the confusion between «server» and «service» in the project description, the docker run guillotina/guillotina in the readme, the Python example given very early in the docs, and the training docs that manipulate behaviours via HTTP endpoints.

I believe it lacks some kind of rationale. What can be done with Guillotina that is really hard to do with other toolkits? Eric told about your use-cases at Onna and found them really enlightening.

I think it would help to explain really soon in the docs the concepts of container, application and addon.
A glossary may also be helpful for non-plone devs.

I found very confusing the difference between an application and an addon (e.g. guillotina_myaddon is the name of the application in the example, and installing the todo application is done on /@addons in the narrative docs)

Content types mean a different thing in HTTP API world. It seems the docs would be clearer if they were called «models».

Why tid? Why not oid like object-id?

Well, those were my 2 cents :) I was just curious, and thought my feedback could be helpful if you plan on reworking the docs!

Enjoy!

[vangheem]

Thank you for this. This is a great overview of the issues right now with docs + design.

A few of the items you mention were issues when I did the training so you're not alone. Additional, you provide a great reference to where we need to improve.

[albertcasado]

@vangheem
Close it if mke no sense or add to the 11 of may milestone