Capítulo 1. Visão Geral

Esta tradução pode estar desatualizada. Para ajudar com as traduções, acesse a ferramenta de traduções do FreeBSD.

Índice

Seja bem vindo ao Projeto de Documentação do FreeBSD.(FDP). Documentação de boa qualidade é muito importante para o sucesso do FreeBSD, e nós valorizamos muito suas contribuições.

Este documento descreve como o FDP é organizado, como escrever e como submeter documentos, e como utilizar de forma efetiva as ferramentas que estão disponíveis.

Todos são bem vindos para se juntar ao FDP. A vontade de contribuir é o único requisito de adesão.

Este primer mostra como:

  • Compreender o papel da documentação e seu lugar no ecossistema.

  • Identificar quais partes do FreeBSD são mantidas pelo FDP.

  • Instalar as ferramentas e arquivos de documentação necessários.

  • Realizar alterações na documentação.

  • Enviar de volta alterações para revisão e inclusão na documentação do FreeBSD.

1.1. Documentação no Ecossistema FreeBSD

Todos os documentos são para o benefício de seus leitores, não de seus escritores ou zeladores. Eles devem se adaptar ao leitor e não esperar que o leitor se adapte a eles.

Nunca culpe o leitor por:

  • ser incapaz de fazer uso de um documento facilmente ou de tudo

  • achar o documento confuso

  • não entender o documento ou como utilizá-lo

  • não encontrar uma resposta explícita ou preencher lacunas com sucesso (ou conectando pontos) para raciocinar em direção a uma

Em vez disso, reconheça que o documento é:

  • inacessível

  • confuso

  • difícil de entender ou utilizar

  • incompleto

Em seguida, faça o documento:

  • mais acessível

  • menos confuso

  • mais claro

  • mais completo

Use os seguintes métodos:

  • aplique as melhores práticas de acessibilidade para corrigir o problema relatado e quaisquer outros semelhantes que você encontrar

  • refazer ou esclarecer a estrutura ou linguagem confusa

  • adicionar exemplos relevantes para a parte que é difícil de entender ou aplicar

  • preencha as lacunas ou adicione os degraus que faltam

1.2. Introdução

Algumas etapas preparatórias devem ser seguidas antes de editar a documentação do FreeBSD. Primeiro, se registre na lista de discussão do projeto de documentação do FreeBSD. Alguns membros do time também interagem no IRC, canal #bsddocs na rede EFnet. Estas pessoas podem ajudar com questões e problemas envolvendo documentação.

1.2.1. Processo de instalação do FreeBSD

  1. Instale esses pacotes. O meta-port docproj instala todos os aplicativos necessários para editar e compilar a documentação do FreeBSD.

    # pkg install docproj

  2. Obtenha uma cópia local da árvore de documentação do FreeBSD em ~/doc (ver A Área de Trabalho).

    % git clone https://git.FreeBSD.org/doc.git ~/doc

  3. Edite os arquivos de documentação que precisam de alterações. Se um arquivo precisar de grandes mudanças, consulte a lista de discussão para obter informações.

    Revise a saída e edite o arquivo para corrigir os problemas informados e, em seguida, execute novamente o comando para verificar os problemas restantes. Repita até que todos os erros sejam resolvidos.

  4. Sempre realize testes de compilação e revise as alterações antes de submeter algo. Execute make no diretório documentation ou website para gerar a documentação no formato HTML.

    % make

    Para reduzir o tempo de compilação, apenas um idioma pode ser compilado:

    % make DOC_LANG=en

    A saída da compilação é armazenada em ~/doc/documentation/public/en/articles/ e ~/doc/documentation/public/en/books/.

  5. Revise a saída da compilação e certifique-se de que as edições não contenham erros de digitação, problemas de layout ou erros. Se algum erro for encontrado durante o processo de compilação, edite os arquivos com erro para corrigir quaisquer problemas que apareçam e, em seguida, execute o comando de compilação novamente até que todos os erros sejam resolvidos.

  6. Adicione todos os arquivos com git add ., então revise o diff com git diff. Por exemplo:

    % git add .
% git diff --staged

    Certifique-se de que todos os arquivos necessários estejam incluídos, então confirme a mudança em seu branch local e gere um patch com git format-patch

    % git commit
% git format-patch origin/main

    Patch gerado com git format-patch incluirá a identidade do autor e endereços de e-mail, tornando mais fácil para os desenvolvedores aplicarem (com git am) e dar os devidos créditos.

    Para tornar mais fácil para os committers aplicarem o patch em sua cópia de trabalho da árvore de documentação, por favor, gere o .diff da base de sua árvore de documentação.

    No exemplo acima, foram feitas alterações na parte bsdinstall do Handbook.

  7. Submeta o patch or arquivo diff pela web para o sistema de Relatórios de Problema. Se estiver usando o formulário web, insira um Sumário com [patch] descrição curta do problema. Selecione o Componente Documentation. No campo de Descrição, insira uma breve descrição das alterações e quaisquer detalhes importantes sobre elas. Use o botão Add an attachment para anexar o patch ou arquivo diff. Finalmente, pressione o botão Submit Bug para enviar seu diff para o sistema de relatório de problemas.

1.2.2. Processo de instalação GNU/Linux

  1. Instale esses pacotes em sistemas baseados em apt como Debian ou Ubuntu. Em outras distribuições GNU/Linux os nomes dos pacotes podem mudar. Consulte o gerenciador de pacotes da sua distribuição em caso de dúvida.

    # apt install hugo ruby-asciidoctor ruby-asciidoctor-pdf ruby-rouge git bmake

  2. Obtenha uma cópia local da árvore de documentação do FreeBSD em ~/doc (ver A Área de Trabalho).

    % git clone https://git.FreeBSD.org/doc.git ~/doc

  3. Edite os arquivos de documentação que precisam de alterações. Se um arquivo precisar de grandes mudanças, consulte a lista de discussão para obter informações.

    Revise a saída e edite os arquivos para corrigir os problemas informados e, em seguida, execute novamente o comando para verificar os problemas restantes. Repita até que todos os erros sejam resolvidos.

  4. Sempre compile e teste as alterações antes de enviá-las. A execução de bmake nos subdiretórios documentation ou website irá gerar a documentação em formato HTML.

    % bmake run LOCALBASE=/usr

  5. Adicione todos os arquivos com git add ., então revise o diff com git diff. Por exemplo:

    % git add .
% git diff --staged

    Certifique-se de que todos os arquivos necessários estejam incluídos, então confirme a mudança em seu branch local e gere um patch com git format-patch

    % git commit
% git format-patch origin/main

    Patch gerado com git format-patch incluirá a identidade do autor e endereços de e-mail, tornando mais fácil para os desenvolvedores aplicarem (com git am) e dar os devidos créditos.

    Para tornar mais fácil para os committers aplicarem o patch em sua cópia de trabalho da árvore de documentação, por favor, gere o .diff da base de sua árvore de documentação.

  6. Submeta o patch ou arquivo diff file pela web para o sistema de Relatórios de Problema. Se estiver usando o formulário web, insira um Sumário com uma breve descrição do problema. Selecione o Componente Documentation. No campo de Descrição, insira uma breve descrição das alterações e quaisquer detalhes importantes sobre elas e adicione patch no campo Keywords. Use o botão Add an attachment para anexar o patch ou arquivo diff. Finalmente, pressione o botão Submit Bug para enviar seu diff para o sistema de relatório de problemas.

1.2.3. Processo de instalação do macOS®

  1. Instale esses pacotes usando o Homebrew e o RubyGem.

    $ brew install hugo ruby git bmake

  2. Adicione o Ruby ao Path.

    $ echo 'export GEM_PATH="/usr/local/lib/ruby/gems/3.1.0"' >> ~/.zshrc
$ echo 'export PATH="$(brew --prefix ruby)/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc

  3. Adicione o alias do git ao Homebrew, pois git format-patch do git fornecido pela Apple não funcionará com o Phabricator.

    $ echo 'alias git=/usr/local/bin/git' >> ~/.zshrc
$ source ~/.zshrc

  4. Instale o pacote rouge usando RubyGem.

    $ sudo gem install rouge asciidoctor asciidoctor-pdf asciidoctor-epub3

  5. Obtenha uma cópia local da árvore de documentação do FreeBSD em ~/doc (ver A Área de Trabalho).

    $ git clone https://git.FreeBSD.org/doc.git ~/doc

  6. Edite os arquivos de documentação que precisam de alterações. Se um arquivo precisar de grandes mudanças, consulte a lista de discussão para obter informações.

    Revise a saída e edite os arquivos para corrigir os problemas informados e, em seguida, execute novamente o comando para verificar os problemas restantes. Repita até que todos os erros sejam resolvidos.

  7. Sempre compile e teste as alterações antes de enviá-las. A execução de bmake nos subdiretórios documentation ou website irá gerar a documentação em formato HTML.

    $ bmake run USE_RUBYGEMS=YES RUBY_CMD=$(brew --prefix ruby)/bin/ruby

  8. Adicione todos os arquivos com git add ., então revise o diff com git diff. Por exemplo:

    % git add .
% git diff --staged

    Certifique-se de que todos os arquivos necessários estejam incluídos, então confirme a mudança em seu branch local e gere um patch com git format-patch

    % git commit
% git format-patch origin/main

    Patch gerado com git format-patch incluirá a identidade do autor e endereços de e-mail, tornando mais fácil para os desenvolvedores aplicarem (com git am) e dar os devidos créditos.

    Para tornar mais fácil para os committers aplicarem o patch em sua cópia de trabalho da árvore de documentação, por favor, gere o .diff da base de sua árvore de documentação.

  9. Submeta o patch ou arquivo diff file pela web para o sistema de Relatórios de Problema. Se estiver usando o formulário web, insira um Sumário com uma breve descrição do problema. Selecione o Componente Documentation. No campo de Descrição, insira uma breve descrição das alterações e quaisquer detalhes importantes sobre elas e adicione patch no campo Keywords. Use o botão Add an attachment para anexar o patch ou arquivo diff. Finalmente, pressione o botão Submit Bug para enviar seu diff para o sistema de relatório de problemas.

1.3. Conjunto de Documentação do FreeBSD

O FDP é responsável por quatro categorias de documentação do FreeBSD.

  • Handbook: O Handbook almeja ser um compreensivo recurso de referência online para os usuários do FreeBSD.

  • FAQ: O FAQ utiliza um formato curto de pergunta e resposta para abordar dúvidas que são frequentemente realizadas nas listas de discussão e fóruns dedicados ao FreeBSD. Este formato não permite respostas longas e detalhadas.

  • Páginas de Manual: As páginas de manual do sistema de língua inglesa geralmente não são escritas pelo FDP, pois fazem parte do sistema base. Contudo, o FDP pode reformular partes das páginas de manual existentes para torná-las mais claras ou para corrigir imprecisões.

  • Web site: Esta é a presença principal do FreeBSD na web, visite https://www.FreeBSD.org/ e muitos mirrors ao redor do mundo. O site é tipicamente o primeiro contato de um usuário novo com o FreeBSD.

As equipes de tradução são responsáveis por traduzir o manual e o site para diferentes idiomas. As páginas do manual não são traduzidas no momento.

Código fonte do site do FreeBSD, Handbook, e FAQ estão disponíveis no repositório de documentação em https://cgit.freebsd.org/doc/.

Código fonte das páginas de manual estão disponíveis em um repositório diferente localizado em https://cgit.freebsd.org/src/.

As mensagens de commit de documentação podem ser visualizadas com git log. As mensagens de commit também são arquivadas em Mensagens de commit de todas as branches do repositório doc.

Endereço web para ambos os repositórios disponíveis em https://cgit.freebsd.org/doc/ e https://cgit.freebsd.org/src/.

Muitas pessoas tem escrito tutoriais e artigos how-to sobre FreeBSD. Alguns são armazenados como parte dos arquivos FDP. Em outros casos, o autor decidiu manter a documentação separada. O FDP esforça-se para fornecer links para o máximo possível dessas documentações externas.

Última alteração em: 9 de março de 2024 por Danilo G. Baio

Início