Introduce documentation standardization for at all communication levels - #841
Conversation
Deploying contributing-docs with
|
| Latest commit: |
e8122b0
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://77d58648.contributing-docs.pages.dev |
| Branch Preview URL: | https://arch-adr-0034-documentation.contributing-docs.pages.dev |
4ecd36c to
f86488b
Compare
🤖 Bitwarden Claude Code ReviewOverall Assessment: APPROVE Reviewed the single new file in this PR, Code Review DetailsNo new findings. The earlier suggestion about CI link checkers not covering external inbound links was answered by the author (the checkers live in the consuming repositories and validate the links they add); that call is left to the author and human reviewers. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| - Strict-move deletions can break unknown inbound links. Known links are updated at move time and | ||
| link checkers in CI are the mitigation for the rest. |
There was a problem hiding this comment.
🎨 SUGGESTED: CI link checkers don't mitigate the inbound-link risk this bullet names.
Details and rationale
docusaurus.config.js sets onBrokenLinks: "throw", which only catches links within this site. The risk called out here is unknown inbound links — search results, Confluence pages, Jira tickets, external blog posts pointing at contributing.bitwarden.com/architecture/.... Those break silently when the Plan moves architecture/{clients,server,sdk,mobile-clients} and 12 of 28 deep-dive pages out of this repo, and no CI check in this repo or the destination repos will detect it.
Consider naming redirects as the mitigation for external inbound links, e.g. adding @docusaurus/plugin-client-redirects so moved pages redirect to their new homes, with CI link checking covering only the in-site case.
There was a problem hiding this comment.
There's a bit of chicken and egg here. The link checker being referenced are in external repositories. The idea is to have link checkers (for example, in clients) that validate links added to them. Issues will arise with PR ordering, but I don't see a better solution to dead links
withinfocus
left a comment
withinfocus
left a comment
There was a problem hiding this comment.
A few tweaks requested but I already consider this the standard and where we're headed, captured now as truly official.
Audit showed that clients was the one that needed attention, but drift may occur between proposal and acceptance. We need to bring all repos up to compliance
allows for flexibility of implementation without altering the plan
…ndard.md Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
2 participants
📔 Objective
Investigate and recommend a direction for documentation standards at Bitwarden.