Contribuição e melhorias na documentação

A documentação do Couchbase é de código aberto, mas, até recentemente, havia uma série de problemas. Se você quisesse fazer uma alteração substancial ou talvez apenas corrigir um erro de digitação rápido, você se deparava com uma ou mais destas perguntas:

Nem sempre estava claro como ir de um URL de documentação para um arquivo específico no repositório do Github.

Agora, isso mudou. Se você visitar uma página da documentação, verá um link "Editar no GitHub" em cada página. Clique nesse link e você será levado ao GitHub para editar o arquivo diretamente (na primeira vez, será solicitado que você crie uma bifurcação).

Primeiro, visite o site Usando o Failover Gracioso na documentação.

Em seguida, clique no link "Edit on GitHub" (Editar no GitHub).

Neste ponto, você está no GitHub. Supondo que você já tenha usado o Git/GitHub antes, o restante do processo deve ser familiar.

Se ainda não tiver criado uma bifurcação, você será solicitado a fazer isso.

Depois disso, você verá uma tela de edição na qual poderá fazer a alteração.

Depois de fazer uma alteração, clique em "Propose file change" (Propor alteração de arquivo). Você verá uma diferença e poderá criar uma solicitação pull.

Esse é um curso intensivo sobre como contribuir com a documentação. Há um Guia completo sobre como contribuir com os documentos do Couchbase Server.

Observe que, embora esse guia esteja escrito em Markdown, a documentação do Couchbase Server está escrita na linguagem Linguagem de marcação da Darwin Information Typing Architecture (DITA).

Para correções simples de erros de digitação, talvez não seja necessário saber muito sobre DITA, mas para edições mais profundas, você precisará se familiarizar com a sintaxe e/ou uma ferramenta de edição como Oxigênio.

Obrigado aos membros da comunidade que já contribuíram! Esse novo sistema está em funcionamento há apenas alguns meses, mas já recebemos ótimas contribuições. Portanto, tiro meu chapéu para:

Fico impressionado com o fato de termos recebido contribuições tão boas de tantas pessoas tão rapidamente! Obrigado a todos por ajudarem a melhorar a documentação.

Para facilitar a contribuição, o processo de compilação teve que ser aprimorado. Anteriormente, ele envolvia várias etapas manuais: extrair o código-fonte, criar localmente, compactar os resultados, enviá-los por FTP para um servidor, executar manualmente uma ou mais tarefas lentas do servidor de criação. Agora você verá que a etapa de compilação acontece muito mais rapidamente na solicitação pull, e as visualizações são geradas rapidamente.

A revisão de conteúdo também foi aprimorada. Anteriormente, as visualizações só eram possíveis em um único local. Não era possível fazer revisões simultâneas. Isso, combinado com a lentidão das compilações manuais, era frustrante e dificultava a revisão de todas as alterações, muito menos as externas.

Por fim, o backport para outras versões da documentação do Couchbase Server também era um problema. A documentação é armazenada em ramificações separadas para cada versão, portanto, se um problema for levantado e corrigido na versão 4.6, ele também poderá ser aplicado à versão 4.5 e assim por diante. Esse é um processo muito manual, mas um @cb-docs-robot foi criado para automatizar o backporting (que você verá em muitos dos exemplos acima).

Outro recurso que adicionamos é a possibilidade de nos dar feedback sobre a documentação diretamente de seu navegador.

Basta encontrar o "Comentários sobre esta página" no canto inferior direito do navegador, clique nele e escreva o feedback.

Essas melhorias na documentação nos ajudam tanto interna quanto externamente. Esperamos que elas tornem sua experiência com a documentação menos frustrante e mais agradável. Seus comentários são bem-vindos! Dê uma olhada na seção Documentos do Couchbase no GitHub.