Capítulo 1. Visão Geral

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:

  • 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. 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. 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 antes de submeter algo. Execute make no diretório de nível superior da documentação e assim será gerado a documentação no formato HTML.

    % make
  5. Quando as alterações estiverem completas e testadas, gere um "arquivo diff":

    % cd ~/doc
    % git diff > bsdinstall.diff.txt

    Dê ao arquivo diff um nome. No exemplo acima, foram feitas alterações na parte bsdinstall do Handbook.

  6. Submeta o 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 [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 arquivo diff. Finalmente, pressione o botão Submit Bug para enviar seu diff para o sistema de relatório de problemas.

1.2. 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: 7 de maio de 2022 por Pau Amma