Metodologias e ferramentas para geração da documentação do grupo Caelum | Modelagem e Processos de Negócios

Solucionado (ver solução)

Solucionado
(ver solução)

3
respostas

por Estudante

| 255.1k xp | 263 posts

Olá Paulo Silveira, Guilherme Silveira e Sérgio Lopes!

Pesquisei por "documentação" no site da Alura e o que encontrei foram 2 cursos de UML, e o "bizagi com BPMN", pelo conteúdo das aulas acredito que não atenda (ou apenas parcialmente) a minha dúvida. Do contrário, favor me corrijam.

Gostaria de perguntar a vocês como vocês fazem/gerenciam a documentação do grupo Caelum, as principais ferramentas utilizadas (se a documentação é gerada manualmente e/ou automaticamente), na construção da documentação para nós alunos, para os funcionários não diretamente envolvidos com as tecnologias (mas que utilizam vosso sistemas e precisam entender da vossa regra de negócio), e na construção da documentação entre vocês, colegas das áreas de tecnologia em si (programação, mobile, se costumam adicionar comentários nos códigos fontes em si e/ou externamente ao código).

Atte., Elías.

3 respostas

por Paulo Silveira

| 317.4k xp | 754 posts

Instrutor Diretor de Produtos na Alura

16/10/2018

Olá Elías

No sistema da alura e no interno da caelum usamos em especial os testes de unidade como base para saber o que faz cada metodo. Apesar de eu não gostar muito da frase que diz que o teste é a documentação, acredito sim que se encaixa em muitos cenários.

Para integrações, situações mais complicadas e susbsistemas nós temos arquivos markdown comitados diretamente nos repositórios do github.

por Estudante

| 255.1k xp | 263 posts

17/10/2018

Olá Paulo,

Obrigado pelo retorno!

Sobre os arquivos markdown:

Eles são gerados manualmente, automaticamente ou um pouco dos dois?
Quem gera esses arquivos (próprio desenvolvedor, testador, etc)?
Como vocês fazem para manter esta documentação atualizada, existe um procedimento automático (e-mail, etc) ou manual (lembrete no monitor)?

solução!

por Paulo Silveira

| 317.4k xp | 754 posts

Instrutor Diretor de Produtos na Alura

19/10/2018

Sim, são feitos manualmente.

O proprio desenvolvedor, que aqui ele mesmo faz os testes.

Infelizmente nao temos procedimento para lembrar de atualizar. Mas como essa documentacao costuma ser extra para auxiliar pontos mais complicados (como setup do projeto), muitas vezes sao feitos e refeitos, entao todo mundo passar por aquele documento e o revisa. Lembrando que automatizamos ao maximo o deploy e setup do projeto na propria maquina, entao esses documentos acabam sendo bem curtos.