Skip to content

Latest commit

 

History

History
326 lines (290 loc) · 14.3 KB

_index.adoc

File metadata and controls

326 lines (290 loc) · 14.3 KB
Raw
description next path prev showBookMenu tags title weight
Visão geral sobre o Processo de Documentação do FreeBSD
books/fdp-primer/tools
/books/fdp-primer/overview/
books/fdp-primer/preface
true
overview
FreeBSD Documentation Project
quick start
Capítulo 1. Visão Geral
2

Visão geral

Table of Contents

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

2. 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 EFnet. Estas pessoas podem ajudar com questões e problemas envolvendo documentação.

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 crossref:working-copy[working-copy,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.

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

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 crossref:working-copy[working-copy,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.

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

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 crossref:working-copy[working-copy,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.

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

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