Capítulo 1. Visão Geral | FreeBSD Documentation Portal
Description: Visão geral sobre o Processo de Documentação do FreeBSD
Keywords: overview,FreeBSD Documentation Project,quick start

# 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.

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" HUGO_CMD="$(brew --prefix hugo)/bin/hugo"

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: 18 de junho de 2026 por Alexander Ziaee

Anterior
Início
Próximo