diff --git a/.github/ISSUE_TEMPLATE/1-feature_request.md b/.github/ISSUE_TEMPLATE/1-feature_request.md deleted file mode 100644 index 8b2820beb..000000000 --- a/.github/ISSUE_TEMPLATE/1-feature_request.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for this project -title: "" -labels: "enhancement" -assignees: "" ---- - -### Is your feature request related to a problem? Please describe - -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - -### Describe the solution you'd like - -A clear and concise description of what you want to happen. - -### Describe alternatives you've considered - -A clear and concise description of any alternative solutions or features you've considered. - -### Additional context - -Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml b/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml new file mode 100644 index 000000000..ff048285c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/1-idea_suggestion.yml @@ -0,0 +1,43 @@ +name: Documentation idea +description: Suggest an idea for improving documentation +title: "[Idea]: " +body: + - type: textarea + attributes: + label: What is your idea for improving documentation? + description: Describe your idea with as much information as possible. + validations: + required: true + - type: dropdown + attributes: + label: Which product or products does this request relate to? + multiple: true + options: + - F5 DoS for NGINX + - F5 WAF for NGINX + - NGINX Agent + - NGINXaaS for Azure + - NGINX Gateway Fabric + - NGINX Ingress Controller + - NGINX Instance Manager + - NGINX One Console + - NGINX Plus + - Other + validations: + required: true + - type: textarea + attributes: + label: Is this idea related to a larger problem? + description: If you have identified multiple related issues, it might be a design pattern problem. + validations: + required: true + - type: textarea + attributes: + label: What alternative ways are there to implement your idea? + description: There are often multiple ways to something - context is important. + validations: + required: true + - type: textarea + attributes: + label: Any additional information + description: Add any remaining detail for this idea not covered by the above questions. diff --git a/.github/ISSUE_TEMPLATE/2-bug_report.md b/.github/ISSUE_TEMPLATE/2-bug_report.md deleted file mode 100644 index 12a6c787b..000000000 --- a/.github/ISSUE_TEMPLATE/2-bug_report.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -name: Bug report -about: Create a report to help us improve -title: "" -labels: "bug" -assignees: "" ---- - -### Describe the bug - -A clear and concise description of what the bug is. - -### To reproduce - -Steps to reproduce the behavior: - -1. Deploy this project using [...] -2. View output/logs/configuration on [...] -3. See error - -### Expected behavior - -A clear and concise description of what you expected to happen. - -### Your environment - -- Version/release of this project or specific commit - -- Target deployment platform - -### Additional context - -Add any other context about the problem here. - -### Sensitive Information - -Remember to redact any sensitive information such as authentication credentials or license keys. diff --git a/.github/ISSUE_TEMPLATE/2-bug_report.yml b/.github/ISSUE_TEMPLATE/2-bug_report.yml new file mode 100644 index 000000000..f71a3312d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/2-bug_report.yml @@ -0,0 +1,49 @@ +name: Bug report +description: Report an issue with our documentation +title: "[Bug]: " +body: + - type: textarea + attributes: + label: Describe the bug you have identified + description: Explain the problem with as much detail as possible. + validations: + required: true + - type: dropdown + attributes: + label: Which product or products does this request relate to? + multiple: true + options: + - F5 DoS for NGINX + - F5 WAF for NGINX + - NGINX Agent + - NGINXaaS for Azure + - NGINX Gateway Fabric + - NGINX Ingress Controller + - NGINX Instance Manager + - NGINX One Console + - NGINX Plus + - Other + validations: + required: true + - type: textarea + attributes: + label: Steps to reproduce the bug + description: Describe the where the issue occurs. + validations: + required: true + - type: textarea + attributes: + label: What is the expected or desired behaviour? + description: Describe what you expected to happen instead of the bug. + validations: + required: true + - type: textarea + attributes: + label: What environments or versions does this bug affect? + description: Describe the contexts which this bug seems to occur. + validations: + required: true + - type: textarea + attributes: + label: Any additional information + description: Add any remaining detail for this idea not covered by the above questions. \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/3-general_request.yml b/.github/ISSUE_TEMPLATE/3-general_request.yml new file mode 100644 index 000000000..e99203299 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/3-general_request.yml @@ -0,0 +1,55 @@ +name: General request +description: Make a general documentation request. +title: "[Request]: " +body: + - type: textarea + attributes: + label: What would you like the documentation team to work on? + description: Please describe your request with as much detail as possible. + validations: + required: true + - type: dropdown + attributes: + label: Which product or products does this request relate to? + multiple: true + options: + - F5 DoS for NGINX + - F5 WAF for NGINX + - NGINX Agent + - NGINXaaS for Azure + - NGINX Gateway Fabric + - NGINX Ingress Controller + - NGINX Instance Manager + - NGINX One Console + - NGINX Plus + - Other + validations: + required: true + - type: textarea + attributes: + label: Who is the person directly responsible for initiating this request? + description: Name the specific person that made this request. + validations: + required: true + - type: textarea + attributes: + label: Is this request part of a larger initiative or project? + description: If it is, name the project the request relates to. + validations: + required: true + - type: textarea + attributes: + label: Are there important constraints for this request? + description: If the constraints are particularly complex, you may wish to organise a meeting before filing a request. + validations: + required: true + - type: textarea + attributes: + label: Does this request have a due date? + description: You should name any specific date or milestones (Such as "Q3") you have in mind for this request, and any dependencies or blockers affecting it. + validations: + required: true + - type: textarea + attributes: + label: Any additional information + description: Add any remaining detail for this request not covered by the above questions. \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/3-story_task.md b/.github/ISSUE_TEMPLATE/3-story_task.md deleted file mode 100644 index b2f7f117d..000000000 --- a/.github/ISSUE_TEMPLATE/3-story_task.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -name: Story task -about: This template is for a story or task, encompassing a single work item for completion -title: "" -labels: "documentation" -projects: ["nginxinc/32"] -assignees: "" ---- - -*Remove italicized directions as relevant to reduce noise in the issue description.* - -## Overview - -*Written as a user story*. - -**As a** , **I want** , **So I can** . - -## Description - -*Add the finer details of what this task involves and is trying to accomplish. A problem well defined is half-solved*. - -## Acceptance criteria - -*Add any exacting acceptance criteria for the task to be complete. Start with known hard requirements, since they may create blockers.* \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/4-epic_overview.md b/.github/ISSUE_TEMPLATE/4-epic_overview.md deleted file mode 100644 index 53e13124a..000000000 --- a/.github/ISSUE_TEMPLATE/4-epic_overview.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -name: Epic overview -about: This template is for planning an epic, which is a large body of effort involving multiple stories or tasks -title: "" -labels: "epic, documentation" -projects: ["nginxinc/32"] -assignees: "" ---- - -*Remove italicized directions as relevant to reduce noise in the issue description.* - -## Description - -*Write a high-level description of what the body of work for this epic includes.* - -## Goals - -*Describe the intent of the epic and what the intended impact is for this effort.* - -## User stories - -*Add a user story for relevant persona to this epic, who are the stakeholders*. - -**As a** , -**I want** , -**So I can** . - -**As a** , -**I want** , -**So I can** . - -## Tasks - -*Create a simple list of tasks necessary for this epic. Finer details should be kept to sub-issues/tasks/stories.* - -- Example task 1 -- Example task 1 -- Example task 1 -- Example task 1 -- Example task 1 \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/4-story_task.yml b/.github/ISSUE_TEMPLATE/4-story_task.yml new file mode 100644 index 000000000..cfc534d6b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/4-story_task.yml @@ -0,0 +1,40 @@ +name: User story +description: This template is for a single story, encompassing a single work item for completion +title: "[Story]: " +body: + - type: textarea + attributes: + label: Overview + description: Use this section to write user stories. + placeholder: As a user, I want thing, So I can action. + validations: + required: true + - type: dropdown + attributes: + label: Which product or products does this request relate to? + multiple: true + options: + - F5 DoS for NGINX + - F5 WAF for NGINX + - NGINX Agent + - NGINXaaS for Azure + - NGINX Gateway Fabric + - NGINX Ingress Controller + - NGINX Instance Manager + - NGINX One Console + - NGINX Plus + - Other + validations: + required: true + - type: textarea + attributes: + label: Description + description: Add the finer details of what this task involves and is trying to accomplish. + validations: + required: true + - type: textarea + attributes: + label: Acceptance criteria + description: Acceptance criteria are written from a user perspective, and should map to the user stories. + validations: + required: true \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/5-content_plan.md b/.github/ISSUE_TEMPLATE/5-content_plan.md deleted file mode 100644 index d68f7d5c2..000000000 --- a/.github/ISSUE_TEMPLATE/5-content_plan.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -name: Content release plan -about: This template is for a content release plan, typically tied to a product release -title: " v#.# content release plan" -labels: "documentation" -projects: ["nginxinc/32"] -assignees: "" ---- - -*Remove italicized directions as relevant to reduce noise in the issue description.* - -## Overview - -- **Product name**: -- **Release date**: - -A content release plan establishes and tracks the documentation work for a product related to a release. - -Add tickets to this content release plan as sub-issues, and update it as you go along. - -## Description - -*Write a high-level summary of changes expected in this release*. - -## User stories - -**As a** technical writer, -**I want** a content release plan for my product, -**So I can** ensure correct content is released alongside the latest version of the product. - -**As a** product owner, -**I want** a content release plan for my product, -**So I can** ensure the product team includes documentation as part of changes to the product. - -## Tasks - -*Create a simple list of tasks necessary for this content plan. Finer details can be kept to sub-issues.* -*Each task item should have a 1:1 relationship with a documentation item, which could be an engineering issue.* - -- [ ] Update changelog/release notes -- [ ] Update version reference information (Such as technical specifications, version shortcodes) -- [ ] Update any other documentation impacted by changes in this release -- Additional task 1 -- Additional task 2 \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/5-content_plan.yml b/.github/ISSUE_TEMPLATE/5-content_plan.yml new file mode 100644 index 000000000..a5a069e6a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/5-content_plan.yml @@ -0,0 +1,28 @@ +name: Content release plan +description: This template is for a content release plan, typically tied to a product release +title: " v#.# content release plan" +body: + - type: textarea + attributes: + label: Overview + description: A content release plan establishes and tracks the documentation work for a product related to a release. + validations: + required: true + - type: textarea + attributes: + label: Description + description: Write a high-level summary of changes expected in this release. + validations: + required: true + - type: textarea + attributes: + label: User stories + description: As a user, I want thing, So I can action. + validations: + required: true + - type: textarea + attributes: + label: Tasks + description: Create a simple list of tasks necessary for this content plan. Finer details can be kept to sub-issues. + validations: + required: true \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/6-epic_overview.yml b/.github/ISSUE_TEMPLATE/6-epic_overview.yml new file mode 100644 index 000000000..bf7aebb87 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/6-epic_overview.yml @@ -0,0 +1,28 @@ +name: Epic overview +description: This template is for planning an epic, which is a large body of effort involving multiple stories or tasks +title: " " +body: + - type: textarea + attributes: + label: Description + description: Write a high-level description of what the body of work for this epic includes. + validations: + required: true + - type: textarea + attributes: + label: Goals + description: Describe the intent of the epic and what the intended impact is for this effort. + validations: + required: true + - type: textarea + attributes: + label: User stories + description: As a user, I want thing, So I can action. + validations: + required: true + - type: textarea + attributes: + label: Tasks + description: Create a simple list of tasks necessary for this epic. Finer details should be kept to sub-issues/tasks/stories. + validations: + required: true \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3988f3345..3141d7b41 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,14 +34,14 @@ If you'd like to discuss something NGINX-related that doesn't involve documentat ## Submit a pull request -Before making documentation changes, you should view the [documentation style guide](/documentation/style-guide.md) and [Managing content with Hugo](/documentation/writing-hugo.md). +Before making documentation changes, you should view the [documentation style guide](/documentation/style-guide.md) and [Managing content with Hugo](/documentation/hugo-content.md). To understand how we use Git in this repository, read our [Git conventions](/documentation/git-conventions.md) documentation. The broad workflow is as follows: - Fork the NGINX repository - - If you're an F5/NGINX user, you can work from a clone + - If you're an F5/NGINX user, you can branch directly with a clone - Create a branch - Implement your changes in your branch - Submit a pull request (PR) when your changes are ready for review @@ -53,10 +53,9 @@ Alternatively, you're welcome to suggest improvements to highlight problems with 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 +- A new issue is created by +- A maintainer from the F5 team is assigned to the issue; this maintainer shepherds the issue through the subsequent stages in the issue lifecycle +- The maintainer assigns one or more [labels](https://github.com/nginx/documentation/labels) to the issue ## Additional NGINX documentation diff --git a/documentation/README.md b/documentation/README.md index 169a891f5..8bcb841f6 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -2,22 +2,29 @@ This directory contains the documentation for the NGINX Documentation repository. -It's used by the DocOps team to record how we use our tools and instructions for common tasks. +It's used by the documentation team to record how we use our tools and instructions for common tasks. -There's also documentation around our ways of working, and ideas of significance wider than the scope of an issue or pull request. +There's also documentation for our ways of working, and ideas of significance wider than the scope of an issue or pull request. We maintain this information publicly as part of NGINX's commitment to transparency and open source. If you're interested in contributing to the [NGINX documentation website](https://docs.nginx.com/), check out [CONTRIBUTING.md](/CONTRIBUTING.md). -## Topics +## Content workflows -- [Contributing closed content](/documentation/closed-contributions.md) +- [Set up pre-commit](/documentation/pre-commit.md) - [Git conventions](/documentation/git-conventions.md) +- [Managing content with Hugo](/documentation/hugo-content.md) +- [Using include files](/documentation/include-files.md) +- [Contributing closed content](/documentation/closed-contributions.md) + +## Writing guidance + - [Information architecture heuristics](/documentation/ia-heuristics.md) +- [Writing style guide](/documentation/style-guide.md) + +# Ways of working + - [Maintainers etiquette](/documentation/maintainers-etiquette.md) -- [Managing content with Hugo](/documentation/writing-hugo.md) +- [Preparing a good issue](/documentation/prepare-issue.md) - [Proposals](/documentation/proposals/README.md) -- [Set up pre-commit](/documentation/pre-commit.md) -- [Using include files](/documentation/include-files.md) -- [Writing style guide](/documentation/style-guide.md) diff --git a/documentation/writing-hugo.md b/documentation/hugo-content.md similarity index 100% rename from documentation/writing-hugo.md rename to documentation/hugo-content.md diff --git a/documentation/include-files.md b/documentation/include-files.md index 096ba4661..dcec616c4 100644 --- a/documentation/include-files.md +++ b/documentation/include-files.md @@ -16,7 +16,7 @@ The files are located in the [content/includes](https://github.com/nginxinc/docs Putting the previous example in any Markdown file would embed the contents of `content/includes/use-cases/docker-registry-instructions.md` wherever the shortcode was used. -For guidance on other Hugo shortcodes, read the [Managing content with Hugo](/documentation/writing-hugo.md) document. +For guidance on other Hugo shortcodes, read the [Managing content with Hugo](/documentation/hugo-content.md) document. ## Guidelines for include files diff --git a/documentation/prepare-issue.md b/documentation/prepare-issue.md new file mode 100644 index 000000000..6c974c6ae --- /dev/null +++ b/documentation/prepare-issue.md @@ -0,0 +1,46 @@ +# Preparing a good issue + +When [creating a new issue](https://github.com/nginx/documentation/issues/new/choose), many of the templates will guide you to providing important detail. + +We strive to make each issue a single source of truth: as a result, each ticket should contain all of the context required for someone to understand a problem and subsequently be empowered to begin working on it. + +This document exists to explain concepts you may be unfamiliar with, and provide examples of the types and amount of detail preferred. + +## User stories and acceptance criteria + +User stories are written in the following format: + +**As a** \, +**I want** \, +**So I** can \. + +It's written from the perspective of a user, whose priorities are often different from your own. + +The users for each story may map to specific user personas dependent on the required content design complexity. + +A user persona reflects a broad set of demographic criteria, representing a type of person who may have different levels of experience, domain knowledge or priorities. + +Acceptance criteria are used to determine whether or not the need identified as part of a user story is fulfilled. + +Much like the user story, it is the user perspective that defines how acceptance criteria are written. + +Here is a good and bad example of acceptance criteria: + +1. The user can find the information about configuring \ +2. Information about \ has been updated + +The first example focuses on ensuring the work has meaningful impact to help a user. + +The second example is simply a checklist item for managing work, without considering its effectiveness. + +## Design and time constraints + +As part of identifying the scope of changes involved with a particular issue, the maintainer reviewing an issue will need to identify any important constraints. + +Constraints tend to be precise and sensitive in nature, and are used to figure out how a ticket should be prioritized. + +- If an issue involves changing a common noun, it may affect other work priorities +- If an issue is related to an upcoming release, it might need attention soon +- If an issue leaves users in an operable state, it requires intervention immediately + +Clear constraints reduces or removes time that might otherwise be spent clarifying detail around an issue. \ No newline at end of file