Enhancements to docs (Planned)

[asafc]

I thought i will open this issue to let whomever interested what are the pending improvements to docs we are planning to add this week :)

If you have more suggestions, please comment on this issue and i will take this into account.

Planned improvements

• [x] complete the docker tutorial with a full example of how to deploy to production with all security parameters, currently this is only documented in the cli/library tutorial.
• [x] "refactor" getting started tutorials, to better explain the different options and route the reader to the proper tutorial for him/her (i.e: getting to learn about opal and play around, deploying a container, using the library to potentially extend opal for your needs, etc).
• [x] document for options to track policy git repo: using polling, using webhooks, tutorial with github.
• [ ] improve architecture tutorial: add diagrams or more detailed descriptions of the messages that goes between opal server and client, e.g: policy bundle format, etc.
• [ ] expand the core modules docs

[ghost]

Hello, I want to contribute to this can you explain me about the fourth and fifth checklist?

[orweis]

Hi @olinabin2004 - for sure we'd love a hand, though I'm not sure this is a good issue to start with - as it requires intimate knowledge of the communication and execution flows.

How about starting with an easier issue to get to know the project: e.g. https://github.com/permitio/opal/issues/201

In general @filipermit can help you work on docs related tasks, and we'd love the help

CC: @asafc

[maurice-freitag]

I'd like to add that the documentation for triggering data updates via the REST API is kind of lackluster in that it only redirects the reader to the OpenAPI spec. Some insight into how to structure the request body and how the server handles the request would be nice, e.g. setting the dataSourceEntry.data field has some implications that are not explained in the docs.

[orweis]

I agree @maurice-freitag . Feel like taking on the challenge and adding some text there via a pull request? 🙏