Adding missing overview in documentation

[miledxz]

Proposed changes

@sjberman @mpstefan This is just a starter for fixing this, if this works good for you guys I can keep going

fixing this issue: #1609

Problem: inconsistencies in documentation

Solution: adding updates

Closes #ISSUE : #1609

Checklist

Before creating a PR, run through this checklist and mark each as complete.

• I have read the CONTRIBUTING doc
• I have added tests that prove my fix is effective or that my feature works
• I have checked that all unit tests pass after adding my changes
• I have updated necessary documentation
• I have rebased my branch onto main
• I will ensure my PR is targeting the main branch and pulling from my branch from my own fork

[mjang]

Hi @zedGGs . Thanks so much for your contribution! I'm a new NGINX employee, and I'm currently investigating our standards for this issue.

[mjang]

Moved to draft to prevent accidental merge while I investigate our standards for this issue.

[sjberman]

@zedGGs Not quite what we're looking for. Take a look at https://github.com/nginxinc/nginx-gateway-fabric/blob/main/site/content/how-to/configuration/control-plane-configuration.md for an example.

The overview section is always at the top to give the introduction of what the purpose of the doc is. There's also a description in the metadata headers. I'll defer to @mjang or @ADubhlaoich to respond with what our docs pattern should be before moving forward on this.

[ADubhlaoich]

Hello @zedGGs! Thanks for opening a PR.

I think the original issue is unclear: for NGINX documentation we use templates based off of The Good Docs Project: the majority of pages are how-to guides.

An overview is intended for the top of the page to summarize its contents for a reader. It doesn't make much logical sense to have it anywhere further down in the page.

We also specifically avoid using the metadata field in our current documentation due to a bug with the Hugo theme.

[travisamartin]

Hello @zedGGs! Thanks for opening a PR.

I think the original issue is unclear: for NGINX documentation we use templates based off of The Good Docs Project: the majority of pages are how-to guides.

An overview is intended for the top of the page to summarize its contents for a reader. It doesn't make much logical sense to have it anywhere further down in the page.

We also specifically avoid using the metadata field in our current documentation due to a bug with the Hugo theme.

Can we add these details to #1609?

[sjberman]

Closing in favor of #2256