Introduce documentation standardization for at all communication levels - #841
Introduce documentation standardization for at all communication levels#841MGibson1 wants to merge 5 commits into
Conversation
Deploying contributing-docs with
|
| Latest commit: |
1134bca
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://499eebf4.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 Re-reviewed the single new file in this PR, Code Review DetailsNo new findings this pass. The previously posted suggestion about CI link checkers not covering external inbound links was answered by the author (the checkers live in the consuming repositories and validate links they add); leaving that call 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.
| - The doc-currency plugin, which enforces rule 4, publishes in | ||
| [bitwarden/ai-plugins](https://github.com/bitwarden/ai-plugins) and distributes the root CLAUDE.md |
There was a problem hiding this comment.
🎨 This is rather precise, and you could loosen up the language about it being a plugin everyone uses.
There was a problem hiding this comment.
I'm not quite understanding what you mean by precise. Does something like
The doc-corrency plugin, which enforces rule 4, is published at bitwarden/ai-plugins. This plugin adds hooks which allow for easy identification of when local documents needs to be updated as well as adding both local and external documentation update requirements to AI review tools.
I think that drops the implication that everyone uses this locally to assist in doc updates, but makes it clear the intent IS to validate come merge time
There was a problem hiding this comment.
I like what you proposed too, but I merely (and also) meant that you don't need to name the exact plugin nor where it's published vs. more generic statements.
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
2 participants
📔 Objective
Investigate and recommend a direction for documentation standards at Bitwarden.