Conversation
| - Advanced > Distributed Atomic Transactions | ||
| - Migration | ||
|
|
||
| There is one special-purpose FAQ, for VReplication in the Reference. |
There was a problem hiding this comment.
We do have this FAQ as well
https://vitess.io/docs/faq/
There was a problem hiding this comment.
Ah, OK. It's outside the versioned documentation so I missed it. There's a lot of good information here; I'll have a look and revise the analysis and recommendations!
| **Localization & i18n directories**: Are you planning for localization/internationalization | ||
| with regard to site directory structure? | ||
|
|
||
| Yes, there are full versions of the documentation in both English and Chinese. |
There was a problem hiding this comment.
We have been debating removing the Chinese documentation because it is being simply copied over for each new release without any content updates.
There was a problem hiding this comment.
@deepthi You mean you're copying a down-level version of the documentation without the updates for new releases? Which version of the documentation is the current Chinese version?
There was a problem hiding this comment.
I would recommend keeping it, but maybe stop versioning it, or suggest it's archived or deprecated somehow.
There was a problem hiding this comment.
I would recommend keeping it, but maybe stop versioning it, or suggest it's archived or deprecated somehow.
I'd recommend removing it from any release later than the last time it was updated, and redirect from the later releases to that version.
| but it should be presented explicitly as a step in the procedure. | ||
|
|
||
| Further down the page, another backup option, *Using mysqlshell*, has the same shortcomings: | ||
| No actual command is presented. |
There was a problem hiding this comment.
The commands are presented towards the end of the page https://vitess.io/docs/21.0/user-guides/operating-vitess/backup-and-restore/creating-a-backup/
Maybe the page needs to be re-organized.
| path for any problems with a task (the escalation path might be: | ||
| *troubleshooting procedure > Slack Channel > project Issue*). Get rid of the | ||
| [VReplication FAQ](https://vitess.io/docs/21.0/reference/vreplication/faq/) | ||
| in the reference section and put the information in a troubleshooting section. |
There was a problem hiding this comment.
Would you recommend consolidating everything into https://vitess.io/docs/faq/
And potentially renaming that to Troubleshooting?
There was a problem hiding this comment.
@deepthi That's one possibility but there's more than troubleshooting information in the FAQ. See comment above re the FAQ. Let me look into it and I'll add some options to the recommendations.
There was a problem hiding this comment.
See recommendations in the analysis. The good news is that there's a lot of good information in the FAQ. The bad news is that it's outside your versioning regimen. Also, I'm not a fan of FAQs in general. I recommend folding the information into the regular technical documentation.
| Yes, there is a Community link in the site’s menu bar, leading to the Community page. | ||
|
|
||
| **New contributor document**: Is there a document specifically for new contributors/your | ||
| first contribution? |
There was a problem hiding this comment.
https://vitess.io/docs/contributing/
That's for code contributions. Should we have a page for docs contributions?
There was a problem hiding this comment.
@deepthi Yes, or add doc contribution instructions to the code contribution doc.
There was a problem hiding this comment.
Rename this file to analyses/0014-vitess/analysis.md
There was a problem hiding this comment.
@dwelsch-esi - please also rebase this PR from main at HEAD.
There was a problem hiding this comment.
@dwelsch-esi - after you've rebased, also please ensure that all checks are passing.
There was a problem hiding this comment.
Might be good to rebase again given the updates that have just landed for the link checking.
There was a problem hiding this comment.
Also, could you address the GH check failures?
There was a problem hiding this comment.
I just rebased again. I have to go do some mentorship stuff now, but I can check back in on this a bit later.
analyses/0014-vitess/analysis.md
Outdated
| **Release process**: Does your code release process account for documentation creation | ||
| & updates? | ||
|
|
||
| No, neither the [Contribute](https://vitess.io/docs/contributing/) documentation nor | ||
| the [CONTRIBUTING.md](https://github.com/vitessio/vitess/blob/main/CONTRIBUTING.md) | ||
| file in the product repo describes how to contribute documentation. There is no Contribution | ||
| section in the website repo. |
There was a problem hiding this comment.
We have this tool: https://github.com/vitessio/vitess-releaser, which maintainers use to create and ship new major and patch releases of Vitess. This tool lists and automated steps needed for a release, one of them is related to documentation and guides the maintainer on how to create and update the documentation before and after each release:
There was a problem hiding this comment.
@frouioui Does the tool verify that you've updated the release notes?
There was a problem hiding this comment.
It does not do this automatically, there is only a step asking the release lead to review them.
What the tool does automate:
- The creation of a changelog file that lists all Pull Requests that were merged for this release.
- The creation final release notes file, which is a template containing the changelog + a summary file written and reviewed manually by maintainers. This file is later uploaded to the GitHub Release page by the tool.
chalin
left a comment
chalin
left a comment
There was a problem hiding this comment.
See inline comments.
Also, I know that you're still working on this document, but consider addressing the check failures and then keeping the checks passing as the document evolves:
analyses/0014-vitess/analysis.md
Outdated
| > ````--topo_implementation=etcd2 --topo_global_server_address=<comma_separated_addresses> | ||
| > --topo_global_root=/vitess/global | ||
| > ```` |
There was a problem hiding this comment.
This markdown formatting doesn't make sense. First, you can use triple ticks. More importantly, there's probably a newline missing after the code-block opening syntax.
There was a problem hiding this comment.
it's also a bit weird because it's a quote. I've gone in and fixed the newline tho.
There was a problem hiding this comment.
Adding <!-- markdownlint-disable fenced-code-language --> as this is quoted content (if it's incorrectly formatted that needs to be communicated).
@dwelsch-esi, could you double check to make sure this snippet is correct from the source.
Signed-off-by: Dave Welsch <dwelsch@expertsupport.com>
Signed-off-by: Nate W <natew@cncf.io>
Signed-off-by: Nate W <natew@cncf.io>
Signed-off-by: Nate W <natew@cncf.io>
…ubleshooting. Signed-off-by: Dave Welsch <dwelsch@expertsupport.com>
Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com> Signed-off-by: Nate W <natew@cncf.io>
Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com> Signed-off-by: Nate W <natew@cncf.io>
✅ Deploy Preview for cncf-techdocs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
… this analyis. Signed-off-by: Nate W <natew@cncf.io>
Signed-off-by: Nate W <natew@cncf.io>
Signed-off-by: Nate W <natew@cncf.io>
Signed-off-by: Nate W <natew@cncf.io>
Signed-off-by: Nate W <natew@cncf.io>
Signed-off-by: Nate W <natew@cncf.io>
Signed-off-by: Nate W <natew@cncf.io>
nate-double-u
left a comment
nate-double-u
left a comment
There was a problem hiding this comment.
Let's merge this in as is. We've got issues getting opened over in https://github.com/vitessio/website/issues. We can make updates needed in a follow up PR.
|
Thanks for this @dwelsch-esi, and thanks everyone for the reviews. |
5 participants
Resolves: #280