Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[META] Documentation website enhancements w/ engineering support #4455

Open
vagimeli opened this issue Feb 14, 2024 · 9 comments
Open

[META] Documentation website enhancements w/ engineering support #4455

vagimeli opened this issue Feb 14, 2024 · 9 comments
Labels
enhancement New Enhancement Meta

Comments

@vagimeli
Copy link

vagimeli commented Feb 14, 2024

Is your feature request related to a problem? Please describe

Yes. The Docs as Code process can be improved by adding sign offs to development PRs. This would ensure documentation is created and managed alongside the code.

Describe the solution you'd like

Add a task list item (Documentation) through GitHub Actions.

Describe alternatives you've considered

No response

Additional context

No response


Issues:

@vagimeli vagimeli added enhancement New Enhancement untriaged Issues that have not yet been triaged labels Feb 14, 2024
@vagimeli vagimeli changed the title Documentation website repo enhancements w/ engineering support Documentation website enhancements w/ engineering support Feb 14, 2024
@vagimeli
Copy link
Author

cc: @hdhalter @kolchfa-aws

@kolchfa-aws
Copy link

Specifically, we're proposing the following changes:

  • Adding a mechanism so that a developer can indicate if documentation is required for the feature.
  • If documentation is required, preventing the dev PR from being merged until a documentation PR is in place in the doc repo.
  • If the feature adds new APIs, for each new API, the documentation PR must contain a filled out API Template, that provides all parameters, whether they are required or optional, default values, descriptions, and types.

@peterzhuamazon peterzhuamazon removed the untriaged Issues that have not yet been triaged label Feb 19, 2024
@peterzhuamazon peterzhuamazon changed the title Documentation website enhancements w/ engineering support [META] Documentation website enhancements w/ engineering support Feb 19, 2024
@peterzhuamazon
Copy link
Member

Needs more discussion on this specific request.
Will add more acceptance criteria later.

@hdhalter
Copy link
Contributor

hdhalter commented Feb 23, 2024

From Barani:
We will break down this issue in to multiple tasks:
1.) Add mandatory "Need documentation" checklist to all PR's ( similar to DCO check)
2.) If documentation checklist is ticked, automated workflow will add documentation label to the PR and also create an issue in documentation repo referencing the PR.

We can implement similar logic for issues as well.

We can work on gating PR merge as future enhancement.

@peterzhuamazon
Copy link
Member

Have some discussion with Heather offline, and seems like this requires some more testing.
There are generally two models as in opt-in vs. opt-out.

If we do the opt-in model where developers need to check a box or add a label, it does not guarantee the issue creation if the label is missed. If we do the opt-out model then the timing of creating such issues and avoid unnecessary noise is key.

Still need some thoughts and discussion or even a one pager / poc before proceed with implementation.

@vagimeli
Copy link
Author

Have some discussion with Heather offline, and seems like this requires some more testing. There are generally two models as in opt-in vs. opt-out.

If we do the opt-in model where developers need to check a box or add a label, it does not guarantee the issue creation if the label is missed. If we do the opt-out model then the timing of creating such issues and avoid unnecessary noise is key.

Still need some thoughts and discussion or even a one pager / poc before proceed with implementation.

Some ideas to consider: https://about.gitlab.com/blog/2022/10/12/five-fast-facts-about-docs-as-code-at-gitlab/

@peterzhuamazon
Copy link
Member

Working on GitHubApp POC and will send one pager design later.

@peterzhuamazon
Copy link
Member

Seems like core already have a basic workflow for creating the docs issues:
https://github.com/opensearch-project/OpenSearch/blob/main/.github/workflows/create-documentation-issue.yml

@peterzhuamazon peterzhuamazon moved this from In Progress to Backlog in OpenSearch Engineering Effectiveness Jun 17, 2024
@peterzhuamazon peterzhuamazon removed their assignment Jul 1, 2024
@getsaurabh02 getsaurabh02 moved this from 🆕 New to Later (6 months plus) in Engineering Effectiveness Board Jul 18, 2024
@peterzhuamazon
Copy link
Member

We have decided on this workflow:

  1. Use core/plugin issue template to allow contributors to select whether they need to add a doc for their feature with needs-documentation label.
  2. The label will trigger a issue creation in documentation-website repo.
  3. The doc issue will inherit core/plugin issue on assigning users, add release branch, and more.

We will also add other checks later such as block PR merge, link backports to original opened issues, and more later, to help the docs team and core/plugin team avoid missing documentations, and start working on those early on.

Thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New Enhancement Meta
Projects
Status: 📦 Backlog
Development

No branches or pull requests

4 participants