Merge pull request #1 from nginxinc/readme-updates

docs: Community READMEs (and more), iteration 1

.github/CODEOWNERS

@@ -1,3 +1,31 @@
-# Main global owner #
-#####################
-*
+# Each of these groups of CODEOWNERS have approval and merge authority over 
+# the noted directories.
+#
+# If you want to add, modify, or delete files in any of these directories,
+# open a pull request. Then add the appropriate group name (without the `@`)
+# to the list of "Reviewers."
+#
+# Order is important; the last matching pattern takes precedence. 
+# For example, when someone opens a pull request that only modifies files 
+# in the content/nginx-one directory, you should assign @nginxinc/one-docs-approvers
+# as a reviewer.
+# 
+# Lines starting with '#' are comments.
+# Each line is a file pattern followed by one or more owners.
+
+# DocOps
+*                           @nginxinc/nginx-docs
+# NGINX Plus
+content/nginx/*             @nginxinc/plus-docs-approvers
+# NGINX Agent
+content/nginx/nms/agent/*   @nginxinc/agent-docs-approvers
+# NGINX One
+content/nginx-one/*         @nginxinc/one-docs-approvers
+# NGINX Instance Manager
+content/nms/nim/*           @nginxinc/nim-docs-approvers
+content/nim/*               @nginxinc/nim-docs-approvers
+# NGINX App Protect WAF
+content/nap-waf/*           @nginxinc/nap-docs-approvers
+data/nap-waf/*              @nginxinc/nap-docs-approvers
+# NGINX App Protect DoS
+content/nap-dos/*           @nginxinc/dos-docs-approvers

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
+<!-- While we have a changelog for current docs at https://github.com/nginxinc/docs/blob/main/CHANGELOG.md, I'm not convinced -->
+
 ## 1.0.0 (Month Date, Year)
 
-Initial release of the NGINX template repository.
+Initial open source release of the documentation repository for enterprise NGINX products. This is a filtered mirror of an internal repository.

CONTRIBUTING.md

@@ -1,57 +1,92 @@
-# Contributing Guidelines
+# Contributing guidelines
 
-The following is a set of guidelines for contributing to this project. We really appreciate that you are considering contributing!
+The following is a set of guidelines for community contributions to this
+project. We really appreciate your desire to contribute!
 
-#### Table Of Contents
+If you are an F5/NGINX employee, see the following guidance [For F5/NGINX Employees](./F5-NGINX-team-notes.md).
 
-[Getting Started](#getting-started)
+## Table of contents
 
-[Contributing](#contributing)
+- [Report a Bug](#report-a-bug)
+- [Suggest a Feature or Enhancement](#suggest-a-feature-or-enhancement)
+- [Open a Discussion](#open-a-discussion)
+- [Submit a Pull Request](#submit-a-pull-request)
+  - Review our [Git style guide](#git-style-guide)
+  - Review our Documentation [style guide](./templates/style-guide.md)
+- [Issue Lifecycle](#issue-lifecycle)
+- [Content edited elsewhere](#content-edited-elsewhere)
+- [F5 Contributor License Agreement (CLA)](#f5-contributor-license-agreement)
 
-[Code Guidelines](#code-guidelines)
+## Report a bug
 
-[Code of Conduct](/CODE_OF_CONDUCT.md)
+To report a bug, open an issue on GitHub with the label `bug` using the
+available bug report issue template. Before reporting a bug, make sure the
+issue has not already been reported.
 
-## Getting Started
+## Suggest a feature or enhancement
 
-Follow the instructions on the README's [Getting Started](/README.md#Getting-Started) section to get this project up and running.
+To suggest a feature or enhancement, open an issue on GitHub with the label
+`feature` or `enhancement` using the available feature request issue template.
+Please ensure the feature or enhancement has not already been suggested.
 
-<!-- ### Project Structure (OPTIONAL) -->
+## Open a discussion
 
-## Contributing
+If you want to start a conversation with the community and maintainers,
+we encourage you to use
+[GitHub Discussions](https://github.com/nginxinc/oss-docs/discussions).
 
-### Report a Bug
+## Submit a Pull Request
 
-To report a bug, open an issue on GitHub with the label `bug` using the available bug report issue template. Please ensure the bug has not already been reported. **If the bug is a potential security vulnerability, please report it using our [security policy](/SECURITY.md).**
+To contribute to F5 NGINX documentation, follow these steps:
 
-### Suggest a Feature or Enhancement
+- Fork the NGINX repository
+- Create a branch
+- Implement your changes in your branch
+- Submit a pull request (PR) when your changes are ready for review
 
-To suggest a feature or enhancement, please create an issue on GitHub with the label `enhancement` using the available [feature request template](/.github/feature_request_template.md). Please ensure the feature or enhancement has not already been suggested.
+Alternatively, you're welcome to suggest improvements to highlight problems with
+our documentation as described in our [support](./SUPPORT.md) page.
 
-### Open a Pull Request (PR)
+### Git Style Guide
 
-- Fork the repo, create a branch, implement your changes, add any relevant tests, and submit a PR when your changes are **tested** and ready for review.
-- Fill in the [PR template](/.github/pull_request_template.md).
+- Keep a clean, concise and meaningful Git commit history on your branch, rebasing locally and squashing before you submit a PR
+- Follow the guidelines of writing a good commit message as described here <https://chris.beams.io/posts/git-commit/>
+  and summarized in the next few points:
 
-**Note:** If you'd like to implement a new feature, please consider creating a [feature request issue](/.github/feature_request_template.md) first to start a discussion about the feature.
+  - In the subject line, use the present tense ("Add feature" not "Added feature")
+  - In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...")
+  - Limit the subject line to 72 characters or less
+  - Reference issues and pull requests liberally after the subject line
+  - Add more detailed description in the body of the git message (`git commit -a` to give you more space and time in
+    your text editor to write a good message instead of `git commit -am`)
 
-#### F5 Contributor License Agreement (CLA)
+### Documentation style guide
 
-F5 requires all external contributors to agree to the terms of the F5 CLA (available [here](https://github.com/f5/.github/blob/main/CLA/cla-markdown.md)) before any of their changes can be incorporated into an F5 Open Source repository.
+For detailed guidance, see our documentation [style guide](./templates/style-guide.md).
 
-If you have not yet agreed to the F5 CLA terms and submit a PR to this repository, a bot will prompt you to view and agree to the F5 CLA. You will have to agree to the F5 CLA terms through a comment in the PR before any of your changes can be merged. Your agreement signature will be safely stored by F5 and no longer be required in future PRs.
+## Issue lifecycle
+
+To ensure a balance between work carried out by the NGINX team while encouraging community involvement on this project, we use the following
+issue lifecycle:
+
+- A new issue is created by a community member
+- An owner on the NGINX team is assigned to the issue; this owner shepherds the issue through the subsequent stages in the issue lifecycle
+- The owner assigns one or more [labels](https://github.com/nginxinc/oss-docs/issues/labels) to the issue
+- The owner, in collaboration with the community member, determines what milestone to attach to an issue. They may be milestones correspond to product releases
+
+## Content edited elsewhere
 
-## Code Guidelines
+This repository does not include all documentation available at https://docs.nginx.com. Other relevant repositories include:
 
-<!-- ### Go/Python/Bash/etc... Guidelines (OPTIONAL) -->
+- [NGINX Open Source](https://github.com/nginx/nginx)
+- [NGINX Unit](https://github.com/nginx/unit)
+- [NGINX Ingress Controller](https://github.com/nginxinc/kubernetes-ingress/)
+- [NGINX Gateway Fabric](https://github.com/nginxinc/nginx-gateway-fabric)
 
-### Git Guidelines
+You can find documentation source code in the `docs` or `site` subdirectories.
 
-- Keep a clean, concise and meaningful git commit history on your branch (within reason), rebasing locally and squashing before submitting a PR.
-- If possible and/or relevant, use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format when writing a commit message, so that changelogs can be automatically generated.
-- Follow the guidelines of writing a good commit message as described here <https://chris.beams.io/posts/git-commit/> and summarized in the next few points:
-  - In the subject line, use the present tense ("Add feature" not "Added feature").
-  - In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...").
-  - Limit the subject line to 72 characters or less.
-  - Reference issues and pull requests liberally after the subject line.
-  - Add more detailed description in the body of the git message (`git commit -a` to give you more space and time in your text editor to write a good message instead of `git commit -am`).
+## F5 Contributor License Agreement
+
+F5 requires all external contributors to agree to the terms of the F5 CLA (available [here](https://github.com/f5/.github/blob/main/CLA/cla-markdown.md)) before any of their changes can be incorporated into an F5 Open Source repository.
+
+If you have not yet agreed to the F5 CLA terms and submit a PR to this repository, a bot will prompt you to view and agree to the F5 CLA. You will have to agree to the F5 CLA terms through a comment in the PR before any of your changes can be merged. Your agreement signature will be safely stored by F5 and no longer be required in future PRs.

CONTRIBUTING_DOCS.md

@@ -0,0 +1,49 @@
+# Contributing guidelines for experts
+
+If you want to contribute, know Git, and can work from the command line, this page can help you. As noted in the [README](./README.md), we create source content for our documentation in Markdown.
+
+Once you add and/or edit our Markdown source files, you can build the content locally as described on this page.
+Before you [Submit a Pull Request](#submit-a-pull-request), we recommend that you first:
+
+- Set up our [Static site generator](#static-site-generator)
+- If you want to add images, review how to [Include images](#include-images)
+- Learn how to [Build documentation locally](#build-documentation-locally)
+
+## Static site generator
+
+You will need to install Hugo to build and preview docs in your local development environment.
+Refer to the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information.
+
+**NOTE**: We are currently running [Hugo v0.134.2](https://github.com/gohugoio/hugo/releases/tag/v0.134.2) in production.
+
+## Include images
+
+When you set up an image, this is the standard format:
+
+{{< img src="path/to/images/file-name.png" alt="descriptive text for screenreaders" >}}
+
+You'll find images in the [static](../static) subdirectory, in a directory associated with the documentation. For example, if you've set up the `file-name.png`
+image, you should copy that file to the `static/path/to/images` directory.
+
+## Build documentation locally
+
+To build and preview docs in your local development environment, you need to install Hugo.
+Refer to the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information.
+
+## Submit a Pull Request
+
+Follow this plan to contribute a change to NGINX source code:
+
+- Fork the NGINX repository
+- Create a branch
+- Implement your changes in this branch
+- Submit a pull request (PR) when your changes are tested and ready for review
+
+### Add new docs
+
+Consistent with the [Diataxis](https://diataxis.fr) framework, our documentation includes the following content types:
+
+- concept: Helps a customer learn about a specific feature or feature set.
+- tutorial: Walks a customer through an example use case scenario; results in a functional PoC environment.
+- reference: Describes an API, command line tool, config options, etc.; should be generated automatically from source code. 
+- openapi: Contains front-matter and shortcode for rendering an openapi.yaml spec.

F5-NGINX-team-notes.md

@@ -0,0 +1,14 @@
+# For F5/NGINX Employees
+
+This repository is a functional mirror. If you want to make a change to F5/NGINX
+documentation, use the private source repository.
+
+We encourage you to work with community contributors. If you participate in
+PRs, issues, discussions, and more, follow these guidelines:
+
+- Follow the [Code of Conduct](./CODE_OF_CONDUCT.md).
+- Be helpful. We want to encourage people who contribute to continue.
+- Avoid references and links to internal content. 
+- Do not include information about future releases, changes, or features, unless
+  specifically authorized.
+- Do not include information that is proprietary to and/or private within F5/NGINX.