docs: Revise docs index page wording #7805

charlieegan3 · 2025-07-30T14:41:03Z

added link to playground
removed some examples I felt were redundant
made the constants example relevant to the example domain
minor wording changes and fixes

charlieegan3 · 2025-07-30T14:41:31Z

docs/docs/index.md

-1. Servers reachable from the Internet must not expose the insecure 'http' protocol.
-2. Servers are not allowed to expose the 'telnet' protocol.
-```
+> 1. Servers reachable from the Internet must not expose the insecure 'http' protocol.


blockquotes have no hscroll

charlieegan3 · 2025-07-30T14:41:51Z

docs/docs/index.md

-All the servers, networks, and ports are provisioned by a script. The script
-receives a JSON representation of the system as input:
+All the servers, networks, and ports are provisioned using infrastructure as
+code. The infrastructure configuration is specified in this JSON representation:


it's 2025, people don't use scripts any more right? 😉

charlieegan3 · 2025-07-30T14:42:29Z

docs/docs/index.md

+This section covers the building blocks of writing policies in Rego. You can see
+how these concepts come together to solve our network security policy in the
+[Complete Example](#complete-example).
+:::


i felt this was needed since the section here is not 100% on the task of building the final example.

charlieegan3 · 2025-07-30T14:43:01Z

docs/docs/index.md

-
-You can omit the `;` (AND) operator by splitting expressions across multiple
-lines. The following query has the same meaning as the previous one:
+Multiple expressions can be combined using logical AND. For queries to produce


I felt this section was too much detail, so I have condensed it.

Will people understand that we're referring to ; as the AND operator here? This is a place where Rego diverges from most other languages people are used to.
Maybe its more clear if we just drop the Multiple expressions can be combined using logical AND part(?).

netlify · 2025-07-30T14:43:24Z

✅ Deploy Preview for openpolicyagent ready!

Name	Link
🔨 Latest commit	`23ecc4d`
🔍 Latest deploy log	https://app.netlify.com/projects/openpolicyagent/deploys/688b2b1a2f624b00082636cb
😎 Deploy Preview	https://deploy-preview-7805--openpolicyagent.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

charlieegan3 · 2025-07-30T14:43:28Z

docs/docs/index.md


 output if {
    input.servers[0].id == "app"
+    // highlight-next-line


this is what needed the style changes, they looked dark to me on lightmode.

charlieegan3 · 2025-07-30T14:44:15Z

docs/docs/index.md


 <RunSnippet files="#input.json" command="data.servers.output"/>

-Variables are immutable. OPA reports an error if you try to assign the same


I mention they're immutable above now, and felt this was too much detail for the homepage.

charlieegan3 · 2025-07-30T14:44:41Z

docs/docs/index.md

-```
-
-<RunSnippet files="#input.json" command="data.servers.output"/>
+`[{"id": "net1", "public": false}, {"id": "net2", "public": false}, ...]`


I have just included what the data looks like rather than an example that is there with a button just to click to see it.

charlieegan3 · 2025-07-30T14:45:38Z

docs/docs/index.md


 <RunSnippet files="#input.json" command="data.servers.http_server"/>

-Providing good names for variables can be hard. If you only refer to the


we'd prefer the some in style here so have removed, mostly to save reading time.

charlieegan3 · 2025-07-30T14:47:12Z

docs/docs/index.md

-the example above `exists_public_network := true` is the head and `some net in input.networks; net.public` is the body.
-
-You can query for the value generated by rules just like any other value:
+You can query for the value generated by rules just like any other value (such as `input` or your own variables):


I didn't want to repeat too much code in the prose.

charlieegan3 · 2025-07-30T14:47:33Z

docs/docs/index.md

+package servers

-pi := 3.14
+max_allowed_protocols := 5


this seemed more relevant than pi. even if pi is the best constant ever.

charlieegan3 · 2025-07-30T14:48:29Z

docs/docs/index.md

-Congratulations on making it through the introduction to OPA. If you made it
-this far you have learned the core concepts behind OPA's policy language as well
-as how to get OPA and run it on your own.
+Congratulations on completing the introduction to OPA. You have learned the core


'making it though' 😆

that is how I felt by this point...

johanfylling

LGTM 👍

johanfylling · 2025-07-31T08:17:11Z

docs/docs/index.md

-
-You can omit the `;` (AND) operator by splitting expressions across multiple
-lines. The following query has the same meaning as the previous one:
+Multiple expressions can be combined using logical AND. For queries to produce


Will people understand that we're referring to ; as the AND operator here? This is a place where Rego diverges from most other languages people are used to.
Maybe its more clear if we just drop the Multiple expressions can be combined using logical AND part(?).

srenatus

Thank you! It's about time that this page gets some attention and careful edits. 🙌 Nicely done.

srenatus · 2025-07-31T08:32:19Z

docs/docs/index.md

-In the example above `public_network contains net.id if` is the rule head and
-`some net in input.networks; net.public` is the rule body. You can query for the entire
-set of values just like any other value. Using the `in` keyword we can use this
+<RunSnippet id="public_network_set.rego" files="#input.json" command="data.example"/> Using the `in` keyword we can use this


Suggested change

<RunSnippet id="public_network_set.rego" files="#input.json" command="data.example"/> Using the `in` keyword we can use this

<RunSnippet id="public_network_set.rego" files="#input.json" command="data.example"/>

Using the `in` keyword we can use this

- added link to playground - removed some examples I felt were redundant - made the constants example relevant to the example domain - minor wording changes and fixes Signed-off-by: Charlie Egan <[email protected]>

Signed-off-by: Charlie Egan <[email protected]>

charlieegan3 · 2025-07-31T08:36:46Z

Thanks both for the review, have patched that up now.

charlieegan3 commented Jul 30, 2025

View reviewed changes

charlieegan3 force-pushed the revise-docs-index branch from 0f0c247 to de1c6e1 Compare July 30, 2025 14:46

charlieegan3 commented Jul 30, 2025

View reviewed changes

charlieegan3 changed the title ~~docs: Revise index page wording~~ docs: Revise docs index page wording Jul 30, 2025

johanfylling approved these changes Jul 31, 2025

View reviewed changes

srenatus approved these changes Jul 31, 2025

View reviewed changes

Charlie Egan added 2 commits July 31, 2025 08:36

docs: Revise index page wording

75257e3

- added link to playground - removed some examples I felt were redundant - made the constants example relevant to the example domain - minor wording changes and fixes Signed-off-by: Charlie Egan <[email protected]>

docs: touch up after review

23ecc4d

Signed-off-by: Charlie Egan <[email protected]>

charlieegan3 force-pushed the revise-docs-index branch from 0b44a66 to 23ecc4d Compare July 31, 2025 08:36

charlieegan3 merged commit 4647660 into open-policy-agent:main Jul 31, 2025
20 checks passed

BrewTestBot mentioned this pull request Jul 31, 2025

opa 1.7.0 Homebrew/homebrew-core#231889

Merged


		<RunSnippet files="#input.json" command="data.servers.output"/>

		Variables are immutable. OPA reports an error if you try to assign the same


		<RunSnippet files="#input.json" command="data.servers.http_server"/>

		Providing good names for variables can be hard. If you only refer to the

docs: Revise docs index page wording #7805

docs: Revise docs index page wording #7805

Uh oh!

Conversation

charlieegan3 commented Jul 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

netlify bot commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for openpolicyagent ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

johanfylling left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

srenatus left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

charlieegan3 commented Jul 31, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

netlify bot commented Jul 30, 2025 •

edited

Loading