A importância da boa documentação de software

Compartilhe!

Documentação de Software

/* Quando falamos da importância da boa documentação de software, em projetos desta natureza, a imagem acima é talvez a melhor ilustração. É uma imagem “batida”, mas é sempre bom revisitá-la. */

Em projetos de software, quando ha especificação antes da construção, é muito comum o nível da documentação não estar bom, e isso gerar efeitos muito ruins no projeto.

Alguns profissionais entendem que documentação de software (especificação, análise e projeto) é algo apenas para “encher linguiça”, outros fazem com entusiasmo mas esbarram nas “travas culturais” da equipe ou do cliente.

Mas fato é: se for fazer, tem que fazer bem feito. Do contrário, não gera nenhum benefício, apenas prejuízos (não há neutralidade neste contexto).

E muitas das vezes é o cliente, interno ou externo, quem produz parte desta documentação. E em alguns casos, este cliente entrega um material que deixa a desejar, e depois quando o problema estoura passa a responsabilidade para que “aceitou” tal documentação e construiu algo errado.

Neste vídeo há uma breve reflexão sobre a importância de se ter uma boa documentação no projeto de software, e como lidar com isso perante o cliente. É um trecho de um Hangout que fizemos com nossos alunos do curso Engenharia de Requisitos na Real.

curso-engenharia-requisitos-desconto-200-reais-vagas

Todavia, é uma reflexão fundamental para os profissionais da área da nossa área!

Deixe comentários, sugestões, críticas, curtidas etc.! 🙂 Vamos debater!

Engenharia de Software

  • Nilda Bem

    Gostaria da sua opinião sobre esses requisitos. fiz , mas fique um pouco na dúvida se els realmente são requisitos não funcionais e regras de negócio.

    os requisitos não funcionais

    1 – Utilização de imagens que não fujam ao ambiente de convívio do aluno

    2 – Tudo o que concerne ao jogo deve se apresentar de maneira clara para não confundir o aluno.

    3 – Respeitar o conteúdo álgebra da forma como é apresentado pelo plano nacional comum curricular

    4 – Armazenar as informações sobre tempo, erros e acertos

    5 – Gerar um arquivo para acompanhamento de desempenho

    6 – Maquina virtual Java instalada independentemente do S.O

    7 – 30 MB de espaço no HD

    8 – Mínimo de 1GB de memória RAM

    9 – Algum dispositivo de áudio instalado na maquina

    as regras de negócio

    1- Só haverá uma resposta certa para cada questão

    2- Todo o conteúdo abordado deve ter como referência o plano nacional comum curricular

    3- para concluir cada etapa, é necessário fazer obrigatoriamente 4 pontos em até 10 segundos.

    4- na etapa final, o aluno precisa acertar o nome das figuras em até 60 segundos

    5- Não devem ser exibidas opções de respostas iguais

    desde já agradeço!!

    • Plínio Ventura

      Olá Nilda!

      Segue abaixo o consegui entender do seu contexto. Sugiro apenas que reavalie cada item, em relação à nomenclatura, qualidade do nome etc. Para entender melhor sobre ambos os conceitos, você pode estudar estes dois posts:

      http://www.ateomomento.com.br/o-que-e-um-requisito-nao-funcional/
      http://www.ateomomento.com.br/o-que-e-regra-de-negocio/

      *** Requsitos Não-Funcionais ***
      6 – Maquina virtual Java instalada independentemente do S.O
      7 – 30 MB de espaço no HD
      8 – Mínimo de 1GB de memória RAM
      9 – Algum dispositivo de áudio instalado na maquina
      2 – Tudo o que concerne ao jogo deve se apresentar de maneira clara para não confundir o aluno.
      5 – Gerar um arquivo para acompanhamento de desempenho
      1 – Utilização de imagens que não fujam ao ambiente de convívio do aluno

      *** Requisitos Funcionais ***
      3 – Respeitar o conteúdo álgebra da forma como é apresentado pelo plano nacional comum curricular
      4 – Armazenar as informações sobre tempo, erros e acertos
      2- Todo o conteúdo abordado deve ter como referência o plano nacional comum curricular

      *** Regras de Negócio ***
      1- Só haverá uma resposta certa para cada questão
      3- para concluir cada etapa, é necessário fazer obrigatoriamente 4 pontos em até 10 segundos.
      4- na etapa final, o aluno precisa acertar o nome das figuras em até 60 segundos
      5- Não devem ser exibidas opções de respostas iguais

      Abraço!

      • Nilda Bem

        “”Um RF, em tempo de especificação, refere-se a algo que será feito, uma ação a ser realizada pelo sistema.”” Li isso no seu blog sobre RF.

        então: 5 – Gerar um arquivo para acompanhamento de desempenho , não é uma ação e portanto um RF?

        esse outro: 2- Todo o conteúdo abordado deve ter como referência o plano nacional comum curricular. Isso não é o sistema que faz, nem representa ação, pq é RF?

        Não estou desacreditando a sua resposta, só fiquei com dúvida mesmo, espero que não me entenda mal. Obrigada! Fique bem!

        • Plínio Ventura

          Olá Nilda,

          Sobre o 5, soa como um RNF que pode ser encaixado na categoria Integração, pois fala de geração de um arquivo (algo técnico), e neste contexto, vários cuidados devem ser tomados para a especificação deixar clara como é a geração/o arquivo (campos, colunas, rotina de geração, tamanho etc.). Para um RNF deste, é pertinente ter um RF associado.

          Sobre o 2, subentendi que “conteúdo” é parte de uma funcionalidade. De repente pode ser encarado como um RNF que pode ser encaixado na categoria padrão. Lembrando que demanda cuidado para ser especificado para descer no detalhe necessário (parece muito genérico).

          Mas não consigo avançar muito nas sugestões, por desconhecer o escopo onde tais requisitos estão.