{"id":19141574,"url":"https://github.com/reinanhs/docusaurus-example-poc","last_synced_at":"2025-10-08T11:20:56.620Z","repository":{"id":224355987,"uuid":"763031437","full_name":"ReinanHS/docusaurus-example-poc","owner":"ReinanHS","description":"Este repositório no GitHub é destinado a armazenar um experimento que estou desenvolvendo para explorar a filosofia da documentação como código (Docs as Code). Essa abordagem propõe que a documentação seja escrita utilizando as mesmas ferramentas empregadas na codificação do projeto.","archived":false,"fork":false,"pushed_at":"2024-03-08T00:17:51.000Z","size":824,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-22T19:15:24.743Z","etag":null,"topics":["docs-as-code","docusaurus","poc"],"latest_commit_sha":null,"homepage":"https://reinanhs.github.io/docusaurus-example-poc/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ReinanHS.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-25T11:29:36.000Z","updated_at":"2024-02-27T10:37:27.000Z","dependencies_parsed_at":"2024-11-09T07:24:34.153Z","dependency_job_id":"224868c7-2a42-422d-a86a-1f2409d93925","html_url":"https://github.com/ReinanHS/docusaurus-example-poc","commit_stats":null,"previous_names":["reinanhs/docusaurus-example-poc"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ReinanHS/docusaurus-example-poc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReinanHS%2Fdocusaurus-example-poc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReinanHS%2Fdocusaurus-example-poc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReinanHS%2Fdocusaurus-example-poc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReinanHS%2Fdocusaurus-example-poc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ReinanHS","download_url":"https://codeload.github.com/ReinanHS/docusaurus-example-poc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReinanHS%2Fdocusaurus-example-poc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278931982,"owners_count":26070871,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docs-as-code","docusaurus","poc"],"created_at":"2024-11-09T07:23:54.070Z","updated_at":"2025-10-08T11:20:56.604Z","avatar_url":"https://github.com/ReinanHS.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n \u003cimg src=\"https://docusaurus.io/pt-BR/img/docusaurus_keytar.svg\" alt=\"Logo do Docusaurus\" width=\"15%\" /\u003e\n\n# Docusaurus Example POC\n \n\u003c/div\u003e\n\nEste repositório no GitHub é destinado a armazenar um experimento que estou desenvolvendo para explorar a filosofia da documentação como código (Docs as Code). Essa abordagem propõe que a documentação seja escrita utilizando as mesmas ferramentas empregadas na codificação do projeto.\n\nEm síntese, a documentação como código é uma técnica de desenvolvimento e publicação da documentação de projetos usando as mesmas ferramentas e processos aplicados no desenvolvimento do código. Isso envolve manter os arquivos de documentação junto aos de código em um repositório, facilitando o controle de versões.\n\n## Por que Docs-as-code?\n\nOptei por estudar essa filosofia por uma necessidade pessoal sentida ao gerenciar a documentação de meus projetos. Frequentemente, as documentações ficavam dispersas em diferentes plataformas, wikis internas e sistemas de gestão de conteúdo, tornando a publicação de novos documentos um processo trabalhoso.\n\nNesse cenário, surge um grande caos, pois as documentações estão distribuídas em múltiplas plataformas. A busca por informações específicas consome tempo, e, muitas vezes, a documentação encontrada está desatualizada ou duplicada em diferentes locais, exigindo análise para determinar qual versão é a mais recente.\n\nPor exemplo, em minha experiência pessoal, precisei fornecer suporte a um novo colaborador para configurar seu ambiente de desenvolvimento. Haviam várias documentações sobre o mesmo procedimento, mas em plataformas distintas e cada uma redigida de forma única. Isso resultava em instruções conflitantes. As documentações estavam distribuídas da seguinte forma:\n\n- Uma no Google Docs.\n- Duas na página de wiki do GitLab.\n- Uma no Confluence.\n\nComo mencionado, as documentações tornaram-se confusas ao longo do tempo, pois os autores focaram apenas na entrega inicial, raramente atualizando-as posteriormente. Esse cenário beira o caos.\n\nDiante desses problemas, decidi estudar a filosofia do Docs-as-code para encontrar uma solução definitiva para o gerenciamento da documentação nos meus projetos. O Docs-as-code visa unificar a fonte da documentação, em vez de dispersá-la. Ele centraliza todo o conteúdo, facilitando o acesso e contribuição das equipes.\n\n## O que é o Docusaurus?\n\nO Docusaurus é uma ferramenta de código aberto que se destaca na criação de documentações de projetos de forma eficiente e elegante. Desenvolvido pelo Facebook, ele é especialmente útil para projetos que buscam integrar a filosofia do Docs-as-code, proporcionando um meio simplificado e poderoso de gerenciar a documentação junto ao código-fonte.\n\n## A Integração do Docusaurus com a filosofia Docs-as-code\n\nA filosofia do Docs-as-code enfatiza a importância de tratar a documentação com a mesma seriedade e utilizando as mesmas ferramentas que são aplicadas no desenvolvimento do código. Neste contexto, o Docusaurus emerge como uma solução ideal. Ele permite que os documentos sejam escritos em Markdown, uma linguagem de marcação leve, e armazenados em um repositório de código, facilitando o controle de versão e a colaboração.\n\n## Automatização com CI/CD\n\nUm dos principais desafios no gerenciamento de documentação é manter sua atualização e sincronia com as mudanças no código. Aqui, o Docusaurus se alia à prática de integração contínua e entrega contínua (CI/CD). Essa integração permite automatizar o processo de publicação e atualização da documentação sempre que ocorrem mudanças no repositório do projeto.\n\nCom a configuração apropriada, cada `push` no repositório pode acionar uma pipeline de CI/CD que, por sua vez, executa a construção e a publicação da documentação atualizada. Isso garante que a documentação esteja sempre alinhada com a versão mais recente do código, melhorando a confiabilidade e a acessibilidade das informações para os usuários e desenvolvedores.\n\nAdicionalmente, estou considerando a inclusão de ferramentas específicas para validação ortográfica e de estrutura de arquivos no nosso processo de CI/CD. Essas ferramentas são essenciais para garantir a qualidade e a precisão da documentação, alinhando-as com os padrões estabelecidos. As principais ferramentas que estou avaliando para integrar a nosso fluxo de CI/CD são:\n\n- [Vale.sh](https://vale.sh/): Esta é uma ferramenta de linting de linguagem extremamente versátil e configurável, projetada para validar a escrita em termos de estilo, gramática e legibilidade. Ela pode ser personalizada para seguir uma variedade de guias de estilo, tornando-a ideal para manter a consistência e qualidade na documentação.\n- [Grammarly](https://www.grammarly.com/): É uma ferramenta avançada de verificação gramatical e ortográfica, conhecida por sua precisão em detectar uma ampla gama de erros de escrita. Sua integração ao nosso fluxo de CI/CD ajudaria a aprimorar a clareza, a correção gramatical e a eficácia da comunicação em nossos documentos.\n\nA incorporação destas ferramentas no nosso processo de CI/CD não apenas aprimorará a qualidade da nossa documentação, mas também automatizará a revisão de textos, economizando tempo e esforço significativos. Isso assegura que os documentos se mantenham não apenas tecnicamente precisos, mas também bem escritos e fáceis de entender.\n\n## Conclusão\n\nEste projeto representa apenas o início de uma série de experimentos que estou conduzindo. Estou comprometido em compilar e compartilhar todos os resultados obtidos neste estudo. Planejo publicar um artigo detalhado no Medium, onde abordarei as descobertas e insights adquiridos durante este processo. Para aqueles que têm interesse no tema, recomendo que acompanhem meu perfil no Medium. Fiquem atentos para a publicação deste material, que em breve estará disponível para leitura. Sua visita e feedback serão muito valiosos para o contínuo desenvolvimento deste e de futuros projetos.\n\n- [Medium @reinanhs](https://medium.com/@reinanhs)\n\n## Changelog\n\nPor favor, veja [CHANGELOG](CHANGELOG.md) para obter mais informações sobre o que mudou recentemente.\n\n## Seja um dos contribuidores\n\nSinta-se à vontade para contribuir com melhorias, correções de bugs ou adicionar recursos a este repositório. Basta criar um fork do projeto, fazer as alterações e enviar um pull request. Suas contribuições serão bem-vindas!\n\nQuer fazer parte desse projeto? leia [como contribuir](CONTRIBUTING.md).\n\n## Licença\n\nEste projeto é licenciado sob a Licença MIT. Veja o arquivo [LICENÇA](LICENSE) para mais detalhes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freinanhs%2Fdocusaurus-example-poc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freinanhs%2Fdocusaurus-example-poc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freinanhs%2Fdocusaurus-example-poc/lists"}