path: root/documentation/content/pt-br/books/fdp-primer/overview/_index.adoc

---
description: 'Visão geral sobre o Processo de Documentação do FreeBSD'
next: books/fdp-primer/tools
params:
  path: "/books/fdp-primer/overview/"
prev: books/fdp-primer/preface
showBookMenu: 'true'
tags: ["overview", "FreeBSD Documentation Project", "quick start"]
title: 'Capítulo 1. Visão Geral'
weight: 2
---

[[overview]]
= Visão geral
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:sectnumoffset: 1
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/fdp-primer/

ifdef::env-beastie[]
ifdef::backend-html5[]
:imagesdir: ../../../../images/{images-path}
endif::[]
ifndef::book[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
toc::[]
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]

ifndef::env-beastie[]
toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]

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.

[[overview-documentation-ecosystem]]
== 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 link:https://webaim.org/intro/#principles[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

[[overview-quick-start]]
== Introdução

Algumas etapas preparatórias devem ser seguidas antes de editar a documentação do FreeBSD. Primeiro, se registre na {freebsd-doc}. Alguns membros do time também interagem no IRC, canal `#bsddocs` na rede http://www.efnet.org/[EFnet]. Estas pessoas podem ajudar com questões e problemas envolvendo documentação.

[[freebsd-installation-process]]
=== Processo de instalação do FreeBSD

[.procedure]
====
. Instale esses pacotes. O _meta-port_ `docproj` instala todos os aplicativos necessários para editar e compilar a documentação do FreeBSD.
+
[source, shell]
....
# pkg install docproj
....
+
. Obtenha uma cópia local da árvore de documentação do FreeBSD em [.filename]#~/doc# (ver crossref:working-copy[working-copy,A Área de Trabalho]).
+
[source, shell]
....
% git clone https://git.FreeBSD.org/doc.git ~/doc
....
+
. 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.
+
. *_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.
+
[source, shell]
....
% make
....
+
Para reduzir o tempo de compilação, apenas um idioma pode ser compilado:
+
[source, shell]
....
% make DOC_LANG=en
....
+
A saída da compilação é armazenada em [.filename]#~/doc/documentation/public/en/articles/# e [.filename]#~/doc/documentation/public/en/books/#.
+
. 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.
+
. Adicione todos os arquivos com `git add .`, então revise o diff com `git diff`. Por exemplo:
+
[source, shell]
....
% 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`
+
[source, shell]
....
% 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.
+
[IMPORTANT]
======
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 [.filename]#.diff# da base de sua árvore de documentação.
======
+
No exemplo acima, foram feitas alterações na parte [.filename]#bsdinstall# do Handbook.
+
. Submeta o patch or arquivo diff pela web para o sistema de https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[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 btn:[Add an attachment] para anexar o patch ou arquivo diff. Finalmente, pressione o botão btn:[Submit Bug] para enviar seu diff para o sistema de relatório de problemas.
====

[[gnu-linux-installation-process]]
=== Processo de instalação GNU/Linux

[.procedure]
====
. 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.
+
[source, shell]
....
# apt install hugo ruby-asciidoctor ruby-asciidoctor-pdf ruby-rouge git bmake
....
+
. Obtenha uma cópia local da árvore de documentação do FreeBSD em [.filename]#~/doc# (ver crossref:working-copy[working-copy,A Área de Trabalho]).
+
[source, shell]
....
% git clone https://git.FreeBSD.org/doc.git ~/doc
....
+
. 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.
+
. 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.
+
[source, shell]
....
% bmake run LOCALBASE=/usr
....
+
. Adicione todos os arquivos com `git add .`, então revise o diff com `git diff`. Por exemplo:
+
[source, shell]
....
% 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`
+
[source, shell]
....
% 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.
+
[IMPORTANT]
======
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 [.filename]#.diff# da base de sua árvore de documentação.
======
+
. Submeta o patch ou arquivo diff file pela web para o sistema de https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[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 btn:[Add an attachment] para anexar o patch ou arquivo diff. Finalmente, pressione o botão btn:[Submit Bug] para enviar seu diff para o sistema de relatório de problemas.
====

[[mac-os-installation-process]]
=== Processo de instalação do macOS(R)

[.procedure]
====

. Instale esses pacotes usando o link:https://brew.sh/[Homebrew] e o link:https://rubygems.org/[RubyGem].
+
[source, shell]
....
$ brew install hugo ruby git bmake
....
+
. Adicione o Ruby ao Path.
+
[source, shell]
....
$ echo 'export GEM_PATH="/usr/local/lib/ruby/gems/3.1.0"' >> ~/.zshrc
$ echo 'export PATH="$(brew --prefix ruby)/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc
....
+
. Adicione o alias do git ao Homebrew, pois `git format-patch` do git fornecido pela Apple não funcionará com o Phabricator.
+
[source, shell]
....
$ echo 'alias git=/usr/local/bin/git' >> ~/.zshrc
$ source ~/.zshrc
....
. Instale o pacote rouge usando RubyGem.
+
[source, shell]
....
$ sudo gem install rouge asciidoctor asciidoctor-pdf asciidoctor-epub3
....
+
. Obtenha uma cópia local da árvore de documentação do FreeBSD em [.filename]#~/doc# (ver crossref:working-copy[working-copy,A Área de Trabalho]).
+
[source, shell]
....
$ git clone https://git.FreeBSD.org/doc.git ~/doc
....
+
. 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.
+
. 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.
+
[source, shell]
....
$ bmake run USE_RUBYGEMS=YES RUBY_CMD="$(brew --prefix ruby)/bin/ruby" HUGO_CMD="$(brew --prefix hugo)/bin/hugo"
....
. Adicione todos os arquivos com `git add .`, então revise o diff com `git diff`. Por exemplo:
+
[source, shell]
....
% 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`
+
[source, shell]
....
% 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.
+
[IMPORTANT]
======
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 [.filename]#.diff# da base de sua árvore de documentação.
======
+
. Submeta o patch ou arquivo diff file pela web para o sistema de https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[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 btn:[Add an attachment] para anexar o patch ou arquivo diff. Finalmente, pressione o botão btn:[Submit Bug] para enviar seu diff para o sistema de relatório de problemas.
====

[[overview-doc]]
== 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/[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 link:{dev-commits-doc-all}.

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.