Skip to content

Latest commit

 

History

History
55 lines (34 loc) · 3.31 KB

doc.md

File metadata and controls

55 lines (34 loc) · 3.31 KB

Como escrevemos uma documentação

Uma boa documentação serve para compartilhar o entendimento sobre como funciona, o que foi feito e por quê foi feito.

Existem diversos tipos de documentação e o que deve ser documentado varia de acordo com o tipo e a complexidade do produto.

Documentação de API

Toda API desenvolvida para ser consumida por alguém ou por algum software precisa ser documentada corretamente.

Na brainn.co utilizamos o padrão API Blueprint por possuir uma sintaxe simples e fácil de aprender. Dependendo do projeto podemos gerar um documento HTML ou disponibilizar no site apiary.io .

Documento de Decisão de Arquitetura

Algumas vezes algumas são tomadas decisões difícies de entender para quem não faz parte do projeto mas que fazem sentido em determinado contexto.

Por exemplo, questões como escolha da linguagem de programação, do banco de dados e configuração do servidor, geralmente fazem muito sentido no início do projeto mas anos depois um desenvolvedor novo pode chegar e fazer um mal julgamento dessas escolhas pois no cenário atual dele há uma visão sobre outras escolhas que fazem mais sentido.

Todas as nossas decisões de arquitetura devem ser documentadas para que outras pessoas entendam o motivo dessas decisões no momento que foram tomadas.

Chamamos esse tipo de documento de ADR (Architecture Decision Record) e eles devem ser escritos conforme o exemplo abaixo:

Create our initial home page Create the brainn's home page containing only the animated logo.

  • Status : accepted
  • Context : We don't have enough information and content to put on our site. We just have a logo.
  • Decision : We decided to create a simple home page contains only an animated logo. We put the animation into the SVG file because it is more elegant and fast than to use CSS3 animations. The dot/circle present in the logo starts like a big circle and after 0.5s it becomes a small circle.
  • Consequences : It works well but if it is necessary changes the logo, the design team will need to export the image as SVG and the dev team will need to edit this file and apply the animation again.

Crie o diretório docs/adr dentro da raiz do projeto e crie um arquivo markdown para cada decisão a ser documentada. O padrão do nome desse arquivo deve ser:

YYYY-MM-DD_Title-In-CamelCase-Separated-By-Hyphen
# Ex.: 2017-01-29_Create-Our-Initial-Home-Page.md

O conteúdo do arquivo deve seguir o template abaixo:

# Title

Description

- **Status:**:
- **Context**:
- **Decision**:
- **Consequences**:
  • Title : short present tense imperative phrase, less than 50 characters, like a git commit message.
  • Status : proposed, accepted, rejected, deprecated, superseded, etc.
  • Context : what is the issue that we're seeing that is motivating this decision or change.
  • Decision : what is the change that we're actually proposing or doing.
  • Consequences : what becomes easier or more difficult to do because of this change.

Em algum momento os produtos desenvolvidos pela brainn.co serão entregues para outros desenvolvedores responsáveis pela manutenção do código e melhorias. Devemos facilitar ao máximo o trabalho deles.

Saiba como contribuir