Para mim, o maior custo não é criar o primeiro site de documentação, mas impedir que ele se afaste do produto depois de algumas versões. Eu consideraria trocar de ferramenta se essa verificação fizesse parte do build: links e âncoras quebrados, assets ausentes, exemplos executáveis quando possível, versões, canonical/hreflang entre idiomas e uma falha clara no CI.

Outro diferencial seria o preview reproduzir exatamente o resultado estático e mostrar, antes do deploy, alterações na navegação e nos metadados. O docshelf check já parece ir na direção certa. Talvez valha separar erros que devem interromper o build de avisos editoriais e permitir regras por projeto. Isso preservaria a simplicidade sem transformar a configuração em outro framework.