A Importância de Uma Boa Documentação

05/05/22, 22:01 A importância de uma boa Documentação - DEV Community
Daniel Reis
Posted on 30/03
A importância de uma boa Documentação

#markdown #docs #braziliandevs #beginners
Prólogo
Uma das discussões mais recentes do nosso querido TwitterDev é sobre algo que eu,
como criador de conteúdo e como pessoa que gosta de documentar ideias e projetos
acho exagerado ter que escolher um dos extremos, onde: "sim é muito bom
documente tudo" OU "não documente nada pois o código precisa ser legível".
No contexto de tecnologia, uma documentação "boa" é muito mais que um código

legível ou um PDF com 100 mil detalhes. Mas sim, conseguir mostrar com simplicidade
o objetivo do que você pretende documentar e nisso usaremos o Markdown para nos
auxiliar.
O tal do Markdown
O markdown é uma linguagem de marcação que tem como ideia converter do seu
modelo para o bom e velho HTML. Inclusive, esse artigo está sendo escrito em
Markdown.
Quando falamos em marcação de texto, pensa em tudo que você consegue fazer no
Microsoft Word ou no Bloco de Notas em questão de aplicar:
https://dev.to/danielhe4rt/a-importancia-de-uma-boa-documentacao-5686 1/15
Cabeçalhos;
Marcadores;
Negrito, Itálico, Sublinhado;
Divisões;
Alinhamento de texto;
etc.
Vou deixar você dar uma pesquisada e lembrando que o VS Code já tem um leitor
nativo! Explore o markdown e suas possibilidades.
Tipos de Documentações
No quesito docs, temos uma lista enorme de coisas que deveriam ter uma devida
atenção quando falamos desse assunto. E isso não se refere só a coisas que você vai
usar no seu profissional. Então vamos listar o que você pode pensar em começar a
documentar:
Estudos
Issues
Pull Requests
Escopos de Projeto
Documentação Técnica
Blocos de Código (Docblocks)
Documentação de estudos
Uma das coisas que somos ensinados desde criança enquanto na escola é, que é
""IMPORTANTE"" documentar as coisas de um jeito que você entenda, num caderno
(assim como os íncas) pra ser um lugar de fácil acesso onde você possa buscar algo
sobre aquele determinado assunto.
Quando estamos estudando programação, é a mesma pegada. Se você tá estudando e

não está documentando seu progresso, você pode estar desperdiçando tempo no
quesito crescimento.
No meu modelo de estudo, geralmente quando vou estudar sobre algum tópico, eu
faço as perguntas MAIS TOSCAS possíveis e ao decorrer do meu estudo eu vou
preenchendo essas lacunas, igual nesse modelo aqui ó:
danielhe4rt.php
@danielhe4rt
o melhor jeito de estudar é ir fazendo anotações de coisas q vc
vai achando interessante
consumi muito conteúdo e hoje percebi q n processei nada ai to

olhando as anotações e blau tudo certo dnv
18:03 PM - 20 Mar 2022

Já o nosso querido evangelista da comunidade php, o Marcel (via Twitter) nos mostrou
uma abordagem diferente de como fazer documentações de estudo enquanto está
assistindo à uma palestra/conferencia.
Marcel dos Santos

@marcelgsantos
@danielhe4rt @leocavalcante Olha aqui um exemplo de como
ficam as minhas anotações. Ah, nem todas ficam organizadinhas
assim. Essa tá melhor organizada pois penso em compartilhá-la. ;)
18:30 PM - 20 Mar 2022

Como você vai fazer isso, é inteiramente decidido por você, porém não esqueça de
fazer sua colinha do assunto pra consultar!
Issues
No mundo do open source, temos empresas/comunidades que mostram o quão
organizadas as discussões devem começar sobre determinado assunto em seus
reposítórios.
As famosas Issues do Github, refletem sobre discussões de melhorias, bugs, ideias

futuras e o que mais você quiser trazer para aquele projeto. Porém, se não for
organizado vai virar bagunça.
Issue do repositório do VS Code
Na print acima vemos que existe um template de Issue onde:
Issue Type: **Bug**
Reproducing the bug:
* Ensure Hot Exit is set to onExit
* Create a new jupyter notebook
* Close or reload the window
Actual: **user is prompted to save**

Expected: ** no prompt, files will be restored on next reopen **
OS Version: Windows/Linux/Mac
VS Code Version: Code Insiders 1.66.0
<details>
<summary>Test A/B</summary>
<p>Details about your test</p>
</details>
Esse tipo de documento é tão valido quanto qualquer outro, pois está ajudando
diretamente o time responsável pelo projeto. Dar precisão do que está acontecendo e
como reproduzir, é algo muito valioso quando falamos de Open Source.
E sim, você pode misturar HTML dentro do Markdown! A ideia é usar só quando
markdown não der suporte ao que você queira fazer.
Pull Requests
Continuando no ambiente Open Source, vamos falar de como anunciar melhorias
propostas à um projeto, o tal do PULL REQUEST!
A ideia do Pull Request é trazer novas referências para melhorias, implementações,

hotfixes e qualquer coisa que agregue diretamente no projeto. Se liga nesse
modelinho:
# Changelog
## Descrição curta da atividade
### Trello/Jira URL
* [Task 123](https://linkmaneiro.com.br)

`` `php
echo "Seu código aqui";
`` `
### Mudanças
* {descrição técnica curta da mudança}
Novamente, podemos ver um pouco de organização na documentação que irá gerar o

valor necessário para os mantenedores do projeto entender sobre a melhoria e saber o
quê exatamente analisar.
Escopos de Projeto
Todo começo de freela tem aquela dúvida de "até onde eu devo entregar pra esse
cliente?" ou quando você tá documentando um projeto novo na firma, vem aquele
"qual é a ideia de um entregável?" e isso tudo vem de um negócio chamado ESCOPO
do FUCKING PROJETO!
Qualquer coisa que te ajude a homologar e validar o quê exatamente o cliente tá atrás,
é uma documentação. Por exemplo, se você tá fazendo uma landing page seria
interessante você ter Mapa do Site (sitemap.xml) mostrando o total de paginas, e antes
de qualquer XML a ideia é documentar no nosso bom e velho TXT ou MD pra não ser
enrolado pelos clientes que pedem cada vez mais.
Ideias de documentação de escopos de projeto:
# Landing da Padaria do seu Zé
Cores: #ffccff, #ccffcc #fafafa #cafeee
Tecnologias: HTML, CSS e Bootstrap
* Landing
* Hero
* Pães que são produzidos
* Horário de Funcionamento
* Newsletter
* Sobre Nós
* História da empresa
* História do seu Zé
* Contato
* Formulário que manda e-mail pro seu Zé
Documentação do projeto Open Source: Basement LMS
## Basement LMS
A criação da LMS vai dar ênfase em uma facilidade maior para que outros desenvolvedore
Essa aplicação ainda está em desenvolvimento, caso você queira integrar ao time, mande
`` `
danielhe4rt: hey@danielheart.dev
`` `
### Projeto
1. [] Base do Projeto
1. Tecnologias:
1. [x] Bootstrap 4/5
2. [x] Azure Stream
3. [x] Docker
4. [] Larastan
2. [] Autenticação
* [x] Métodos base: Sessão
* [] Métodos custom: Google, Github e Twitch
3. [] Cursos
1. [] Modelagem Admin
1. [X] Pagina de Criação de cursos
2. [X] Pagina de Criação de módulos
1. [] Ordenação de módulos
3. [X] Pagina de Criação de Lições
1. [X] Lições de Video
2. [X] Lições em Artigos
3. [] Lições em Quiz
4. [] Ordenação de Lições
2. [] Modelagem User
1. [] Pagina inicial com todos os cursos
2. [x] Pagina principal de um curso
3. [x] Pagina para assistir o curso
4. [] Subscrição
1. [] Método de pagamento:
1. [] Stripe
2. [x] GerenciaNet
3. [] Pagarme
4. [] Paypal
2. [] Formulário não pagante: Se não houver condições de comprar, deixa o salve qu

5. Gameficação
1. [] Leveling
1. [] Ao assistir uma aula
2. [] Ao responder um questionário
2. [] Tabela de EXP: definir um algoritmo de leveling pra não se preocupar com banc
6. Landing Page
1. [x] Layout Base com integrações
[........] para mais informações, acesse o repo :p
Nesses dois exemplos, vimos como é possível abstrair documentações dos diferentes
escopos de projeto, e vai da sua ideia entender como fazer isso da melhor maneira.
Novamente, a doc tem que ficar claro para VOCÊ E O CLIENTE!
Documentação Técnica
Vamos assumir que você, joaozinhohe4rt ou mariazinhahe4rt entrou numa empresa

onde a code base é ENORME e você não tem tanto acesso ao time para fazer
perguntas, não seria interessante ter uma DOCUMENTAÇÃO do código?
Em grandes empresas, é obrigatório entregar uma documentação legível para os

clientes sobre como USAR a aplicação, mas poucas empresas lembram da
documentação de como a aplicação foi criada ou o porquê aquele código existe e isso
é bem grave.
Recentemente estava fazendo uma implementação do ACL (Access Control List) na

minha empresa, onde a ideia é gerenciar quais cargos tem acesso à tal parte da
plataforma. Porém, não tinha nenhuma documentação em PT-BR sobre a lib que eu
estaria usando, e o time também desconhecia a ferramenta. Com isso eu decidi criar
uma pasta dentro do projeto chamada docs e junto ao Readme do projeto, começar a
documentar o que eu estava fazendo no código.
E quando chegamos na Feature em si, descrevemos o passo a passo do que você

deveria saber sobre o que foi implementado. Não existe um padrão, mas isso também
conta como algo MUITO VALIOSO para a empresa e para as próximas pessoas que
forem manter o projeto.
Nisso, você joaozinhohe4rt ou mariazinhahe4rt que entrou na empresa, vão ter mais
informações quando forem mexer na tal feature e também atualizar a documentação já
escrita. Bacana né?
Blocos de Código
Agora vamos para o mais polêmico de todos para fechar com chave de ouro! O tal do
docblock que todos abominam ou amam com todas as forças.
Qual é a ideia de um docblock? Documentar uma função em seus minimos detalhes

baseado em sua anatomia. Se liga no exemplo:
/**
* Função para enviar e-mails com um template boladão pra galera que der like nesse po
*
* @author danielhe4rt - hey@danielheart.dev
* @param User $sender
* @param Template $template
* @param array $mailList
* @return void
*/
public function handle(User $sender, Template $template, array $mailList): void
$sender->send($template, $mailList);
O docblock é literalmente esse bloco de comentário gigantão ai que diz o quê a

função faz e também tem outros beneficios, sendo para os interpretadores te ajudarem
na hora do código à te darem uma orientação e também ser intuitivo e descritivo.
Porém como nós podemos ver nos estudos de Clean Code, a ideia é que o código seja
auto descritível e não contenha comentários.
public function dispatchMailing(User $sender, Template $template, array $mailList): vo

{
$sender->sendMailTo($mailList)
->withTemplate($template);
Não temos o docblock mas se você souber o bom e velho inglês, você vai saber
EXATAMENTE o que está acontecendo ali dentro. Quando existem docblocks em
funções, e essas funções são ATUALIZADAS, muitas das vezes é esquecido de verificar
se o que o docblock descreve é realmente o que condiz com a função. Então, isso é
visto como um problema na maior parte do tempo.
O que eu acho de docblocks?

Recentemente comecei um projeto open source e com isso, comecei a fazer minhas
pesquisas em outros projetos que eu utilizo no meu dia a dia. Vi que em aplicações
finais, o clean code sem comentários é o mais recomendado já que tudo vai estar em
constante mudança.
Já nos pacotes que você cria e mantêm para várias pessoas é ALTAMENTE
RECOMENDADO você usar e abusar de docblocks, já que o projeto será mantido por
várias pessoas e deverá ter um critério maior de aceitação nos PR's da vida.
Conclusão
Documentação é algo muito pouco valorizado no inicio da carreira de um

desenvolvedor, porém uma documentação rica em detalhes pode fazer a diferença em
todos os quesitos.
Toda documentação pode virar um conteúdo didático, assim como feito nesse post
pegando referências de posts de Twitter, Issues e Pull Requests de projetos e até
mesmo lendo projetos abertos.
Se você curtiu o conteúdo, deixa aquele likezinho maroto, compartilha no Twitter/IG e

marca nois e até a próxima 💜
Revisores: Flaubordi e Nandaknwls
Discussion (7)
Augusto Kayo • Apr 20

Muito bom esse tópico.
Realmente precisamos anotar tudo que estamos estudando! Principalmente no ramo da

programação a informação é a nossa aliada.
Eu anoto tudo também. Assim eu posso voltar e revisar.
Sempre esqueço algumas syntaxes ou até mesmo esqueço pra que serve tal elemento, as
anotações eu chamo de "Mente digital" kkkkkk la eu armazeno tudo. Exatamente tudo
com relação a programação.Banco de dados, node e etc..
muito bom !
Sobre a questão de documentar o sistema para os futuros usuários é importante

também.
Nunca deixem para trás uma boa e velha anotação, pois, ajuda muito.
Luís Von Muller • Mar 30

👏 Muito bom
Alan Albuquerque Ferreira Lopes • Mar 30

Extremamente necessário! Muito obrigado pela contribuição <3
Jean Carlos dos Santos • Mar 31

Aulas e mais aulas, cada dia o Dan traz novidades para o meu início da vida de dev
Cauê Santos • Mar 30

Boa primo!
Anelise Estevam • Apr 1

Conteúdo importante demais! Salvando aqui pra consultas posteriores.
Rafael-Jose • Apr 4

Unbelievable.
Code of Conduct
•
Report abuse
Daniel Reis
PHP Evangelist > Twitch LiveCoder >

Microsoft MVP >
Coding useless stuff since 2011
LOCATION
São Paulo
EDUCATION
Stackoverflow Researcher
WORK
Developer Advocate
JOINED
13/09/2020
More from Daniel Reis
Melhorando seus Testes com GRAMÁTICA

#testing
#php
#braziliandevs
#programming
Três conceitos para um Código Limpo
#webdev
#beginners
#php
#braziliandevs
Descomplicando o OAuth do Microsoft Graph

#braziliandevs
#azure
#oauth
#graph

A Importância de Uma Boa Documentação - DEV Community

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

A Importância de Uma Boa Documentação - DEV Community

Enviado por

Direitos autorais:

Formatos disponíveis

05/05/22, 22:01 A importância de uma boa Documentação - DEV Community

No contexto de tecnologia, uma documentação "boa" é muito mais que um código

Quando estamos estudando programação, é a mesma pegada. Se você tá estudando e

consumi muito conteúdo e hoje percebi q n processei nada ai to

Marcel dos Santos

As famosas Issues do Github, refletem sobre discussões de melhorias, bugs, ideias

Issue do repositório do VS Code

Na print acima vemos que existe um template de Issue onde:

Issue Type: **Bug**

Reproducing the bug:

* Ensure Hot Exit is set to onExit

* Create a new jupyter notebook

* Close or reload the window

Actual: **user is prompted to save**

VS Code Version: Code Insiders 1.66.0

<p>Details about your test</p>

A ideia do Pull Request é trazer novas referências para melhorias, implementações,

## Descrição curta da atividade

### Trello/Jira URL

echo "Seu código aqui";

* {descrição técnica curta da mudança}

* {descrição técnica curta da mudança}

Novamente, podemos ver um pouco de organização na documentação que irá gerar o

Ideias de documentação de escopos de projeto:

# Landing da Padaria do seu Zé

Cores: #ffccff, #ccffcc #fafafa #cafeee

Tecnologias: HTML, CSS e Bootstrap

* Pães que são produzidos

* Formulário que manda e-mail pro seu Zé

Documentação do projeto Open Source: Basement LMS

1. [x] Bootstrap 4/5

2. [x] Azure Stream

* [x] Métodos base: Sessão

* [] Métodos custom: Google, Github e Twitch

1. [X] Pagina de Criação de cursos

2. [X] Pagina de Criação de módulos

3. [X] Pagina de Criação de Lições

1. [X] Lições de Video

2. [X] Lições em Artigos

1. [] Pagina inicial com todos os cursos

2. [x] Pagina principal de um curso

3. [x] Pagina para assistir o curso

2. [] Formulário não pagante: Se não houver condições de comprar, deixa o salve qu

1. [] Ao assistir uma aula

1. [x] Layout Base com integrações

[........] para mais informações, acesse o repo :p

Vamos assumir que você, joaozinhohe4rt ou mariazinhahe4rt entrou numa empresa

Em grandes empresas, é obrigatório entregar uma documentação legível para os

Recentemente estava fazendo uma implementação do ACL (Access Control List) na

E quando chegamos na Feature em si, descrevemos o passo a passo do que você

Qual é a ideia de um docblock? Documentar uma função em seus minimos detalhes

* @author danielhe4rt - hey@danielheart.dev

* @param User $sender

* @param Template $template

* @param array $mailList

public function handle(User $sender, Template $template, array $mailList): void

O docblock é literalmente esse bloco de comentário gigantão ai que diz o quê a

public function dispatchMailing(User $sender, Template $template, array $mailList): vo

O que eu acho de docblocks?

Documentação é algo muito pouco valorizado no inicio da carreira de um

Se você curtiu o conteúdo, deixa aquele likezinho maroto, compartilha no Twitter/IG e

Issue Type: Bug

Actual: user is prompted to save