xaleeks
commented
3 years ago Hi Orlin, please see some of my thoughts inline. Thanks for bringing this up for discussion
If I write documentation, who verifies that it's technically accurate?
The Contour maintainers should verify the documentation. I’d really appreciate your getting involved in some of the verification as well.
If I'm not a native english speaker, who can I ask for help with grammar and language review?
We can ask the community for any bandwidth they may have and also reach out to CNCF to see if they have any resources. I know @jonasrosland is involved with some other OSS projects that has similar needs, maybe can consolidate efforts a bit.
If I'm a trained technical writer and want to rearrange, create new, or split existing topics, who do I tag in issues/on Slack for comment?
You can tag any of the Contour maintainers really. Feel free to raise the issue in the Contour channel in Kubernetes slack
As a developer user, how can I ensure that content is accurate and up to date? Are alpha and beta features flagged? What happens when content (+ functionality) gets deprecated or changed in a major way?
This is mostly maintained through docs and release notes. We try to call out upcoming deprecations and bumps in the underlying components at least one release ahead of time. If something is alpha or beta, we would call it out in the release notes like we've done with the Contour Operator
Who reviews documentation PRs?
I think at the very least the author of respective the feature should review the documentation PR, and one other maintainer who did the code review for the feature is also a good candidate. It’s a goal of ours to have more than one maintainer be intimately familiar with any major component of Contour even if only one person developed it
github-actions[bot]
Based on https://github.com/cncf/techdocs/blob/main/assessments/0001-contour.md, better Content creation process is needed:
Content creation processes:
Because Contour maintains a Docs+Code monorepo, the CONTRIBUTING.md, Contributing, and How we work pages are all centered around code processes. As a content creator:
Let's discuss the process here!