pratica_prof_projeto_de_desenvolv_sistemas_capitulo_7

Prévia do material em texto

<p>LUCIANA DO AMARAL TEIXEIRA</p><p>Brasília/DF - 2024</p><p>1ª Edição</p><p>Capítulo 6</p><p>Documentação do Sistema</p><p>Prática Profissional – Projeto de</p><p>Desenvolvimento de Sistemas</p><p>Autoria</p><p>Luciana do Amaral Teixeira</p><p>Produção</p><p>Equipe Técnica de Avaliação, Revisão Linguística e Editoração</p><p>3</p><p>Introdução</p><p>A documentação do sistema refere-se ao conjunto de materiais redigidos e artefatos</p><p>construídos que fornecem informações sobre um software. Ele serve como uma ferramenta</p><p>de comunicação vital entre desenvolvedores, designers, testadores, usuários e outras</p><p>partes interessadas envolvidas no processo de desenvolvimento de software. O objetivo</p><p>principal da documentação de software é facilitar compreensão, uso, manutenção e</p><p>colaboração durante todo o ciclo de vida do sistema.</p><p>Figura 54. Documentação de software.</p><p>Fonte: adaptada pela autora de https://www.canva.com/design/DAFkbxyHzkk/OYdRg9NNb00EJOf5JVypJg/edit?utm_</p><p>content=DAFkbxyHzkk&utm_campaign=designshare&utm_medium=link2&utm_source=sharebutton.</p><p>A documentação do software inclui vários tipos de documentos, como manuais do</p><p>usuário, especificações técnicas, documentos de design, comentários de código, arquivos</p><p>README, documentação de API, notas de versão e muito mais. Cada tipo atende a</p><p>diferentes públicos e serve a propósitos específicos. A documentação do usuário, por</p><p>exemplo, destina-se a usuários finais e fornece orientação sobre como usar o software</p><p>de forma eficaz. Pode incluir manuais do usuário, tutoriais, guias, perguntas frequentes</p><p>e quaisquer recursos que ajudem os usuários a navegar pelo aplicativo.</p><p>A documentação técnica, por sua vez, destina-se a desenvolvedores, testadores e outras</p><p>partes interessadas técnicas. Ela se aprofunda no funcionamento interno do software,</p><p>explicando a arquitetura, decisões de design, algoritmos, estruturas de dados e outros</p><p>aspectos técnicos.</p><p>6CAPÍTULO</p><p>DOCUMENTAÇÃO DO SISTEMA</p><p>4</p><p>CAPÍTULO 6 • DOCUMENTAÇÃO DO SISTEMA</p><p>Já a documentação de design se concentra em explicar as escolhas de design feitas durante</p><p>o desenvolvimento do software. Pode incluir diagramas de arquitetura, fluxogramas,</p><p>wireframes e outras representações visuais que descrevem a estrutura e o comportamento</p><p>do software.</p><p>Um wireframe é uma representação visual ou um projeto de um design de interface do usuário</p><p>para um software ou site. É um esboço simplificado e de baixa fidelidade que descreve o layout,</p><p>a estrutura e os elementos básicos da interface do usuário sem focar em cores, gráficos ou design</p><p>visual detalhado. Wireframes são usados nos estágios iniciais do processo de design para definir</p><p>o layout geral e a funcionalidade da interface.</p><p>Figura 55. Wireframe de baixa fidelidade.</p><p>Fonte: adaptada de https://br.freepik.com/vetores-gratis/ilustracao-do-modelo-de-design-da-web_3139740.</p><p>htm#query=low%20fidelity%20wireframe&position=0&from_view=search&track=ai.</p><p>» Design iterativo: wireframes costumam ser usados em um processo de design iterativo, permitindo</p><p>que designers e stakeholders experimentem rapidamente diferentes ideias de layout e obtenham</p><p>feedback no início da fase de design.</p><p>» Ferramenta de comunicação: wireframes atuam como uma ferramenta de comunicação entre</p><p>equipes de design, desenvolvedores, stakeholders e clientes. Eles ajudam todos os envolvidos</p><p>no projeto a visualizar e alinhar o conceito de design inicial.</p><p>» Design centrado no usuário: wireframes contribuem para o design centrado no usuário,</p><p>concentrando-se no layout e nos aspectos de usabilidade da interface antes de investir tempo no</p><p>design visual detalhado. Isso garante que a experiência do usuário seja priorizada desde o início.</p><p>» Design responsivo: wireframes também podem ser usados para planejar o design responsivo</p><p>de um site ou aplicativo, mostrando como o layout se adapta a diferentes tamanhos de tela</p><p>e dispositivos.</p><p>5</p><p>DOCUMENTAÇÃO DO SISTEMA • CAPÍTULO 6</p><p>Figura 56. Wireframe de alta fidelidade.</p><p>Fonte: https://br.freepik.com/vetores-gratis/varias-telas-para-aplicativo-movel-violeta-de-transporte-publico_10504567.</p><p>htm#query=user%20interface%20mockup&position=30&from_view=search&track=ais.</p><p>» Tipos de wireframes: wireframes podem variar de esboços simples desenhados à mão a</p><p>representações digitais mais sofisticadas. Existem diferentes tipos de wireframes, como wireframes</p><p>de baixa fidelidade, wireframes de média fidelidade e wireframes de alta fidelidade, cada um</p><p>atendendo a diferentes propósitos no processo de design.</p><p>Os desenvolvedores geralmente incluem comentários no código-fonte para explicar como</p><p>certas seções funcionam, sua finalidade e quaisquer considerações importantes. Esses</p><p>comentários ajudam outros desenvolvedores a entender o código e fazer modificações</p><p>e são, portanto, considerados parte da documentação.</p><p>Para bibliotecas e estruturas de software, a documentação da API fornece detalhes sobre as</p><p>funções, classes, métodos e parâmetros disponíveis. Isso permite que os desenvolvedores</p><p>entendam como integrar e utilizar a funcionalidade fornecida.</p><p>Por fim, as notas de versão são documentos que acompanham as versões de software e</p><p>detalham as alterações, correções de bugs, melhorias e novos recursos. Eles mantêm os</p><p>usuários e os stakeholders informados sobre as mudanças no software.</p><p>Documentar um aplicativo de software é de suma importância durante todo o ciclo de</p><p>vida do desenvolvimento. Um sistema documentado garante:</p><p>» Entendimento e integração: a documentação abrangente ajuda os novos</p><p>membros da equipe a entenderem rapidamente a arquitetura, as decisões de</p><p>design e a base de código. Isso acelera o processo de integração e permite que</p><p>eles contribuam efetivamente desde o início.</p><p>6</p><p>CAPÍTULO 6 • DOCUMENTAÇÃO DO SISTEMA</p><p>» Manutenção e depuração: código bem documentado é mais fácil de manter e</p><p>depurar. Quando os desenvolvedores podem entender a intenção original por</p><p>trás das seções de código, eles podem fazer modificações com mais eficiência e</p><p>identificar as causas dos problemas.</p><p>» Comunicação: a documentação serve como uma ferramenta de comunicação</p><p>entre desenvolvedores, testadores, designers, gerentes de projeto e stakeholders.</p><p>Ela garante que todos estejam na mesma página em relação às funcionalidades</p><p>e aos requisitos do software.</p><p>» Transferência de conhecimento: a documentação preserva o conhecimento</p><p>institucional. À medida que os membros da equipe vão e vêm, a documentação</p><p>garante que informações importantes sobre o design, a funcionalidade e as</p><p>peculiaridades do software sejam mantidas.</p><p>Figura 57. Vantagens da documentação de software.</p><p>Fonte: adaptado pela autora de https://www.canva.com/design/DAFkbxyHzkk/OYdRg9NNb00EJOf5JVypJg/edit?utm_</p><p>content=DAFkbxyHzkk&utm_campaign=designshare&utm_medium=link2&utm_source=sharebutton.</p><p>6.1 Elaboração e organização da documentação</p><p>A elaboração e a organização da documentação do software contribuem para uma</p><p>comunicação e colaboração eficazes e manutenção do software ao longo do tempo.</p><p>Alguns aspectos-chave relacionados à elaboração e à organização da documentação</p><p>estão listados a seguir.</p><p>» Identificação da audiência: antes de criar documentação, é crucial identificar</p><p>a audiência para a qual ela se destina. A documentação pode ser direcionada a</p><p>desenvolvedores, testadores, designers, usuários finais ou stakeholders. Cada</p><p>público terá necessidades e níveis de compreensão diferentes, o que orientará</p><p>o estilo e o nível de detalhes da documentação.</p><p>7</p><p>DOCUMENTAÇÃO DO SISTEMA • CAPÍTULO 6</p><p>» Definição de objetivos: é importante estabelecer os objetivos da documentação.</p><p>Isso pode incluir facilitar a compreensão do código, fornecer instruções de uso,</p><p>descrever a arquitetura, explicar processos de configuração ou qualquer outro</p><p>propósito específico. Definir objetivos claros ajuda a manter a documentação</p><p>focada e relevante.</p><p>» Escolha de formato: a documentação pode assumir diversos formatos, como</p><p>documentos de texto, wikis, diagramas, tutoriais em vídeo ou até mesmo</p><p>comentários no código-fonte. A escolha do formato deve ser baseada na</p><p>eficácia</p><p>em atender aos objetivos e à audiência.</p><p>Uma wiki é uma plataforma online que permite aos usuários criar, editar e organizar conteúdo de</p><p>forma colaborativa. Ela permite que os indivíduos colaborem na criação e compartilhamento de</p><p>informações de maneira amigável e facilmente acessível. O termo “wiki” vem da palavra havaiana</p><p>“wikiwiki”, que significa “rápido”, refletindo a ênfase da plataforma na criação e edição rápida e</p><p>fácil de conteúdo. Alguns aspectos-chave das wikis são:</p><p>» Wikis são plataformas de edição colaborativa em que múltiplos usuários podem contribuir</p><p>simultaneamente, agregando ao conhecimento coletivo.</p><p>» Elas são, na maioria das vezes, de acesso aberto, mas podem ter controles para restringir edições.</p><p>» O formato do conteúdo é simplificado, usando uma linguagem de marcação de fácil aprendizado.</p><p>» Cada alteração é registrada, permitindo o rastreamento das versões e a possibilidade de reverter</p><p>mudanças.</p><p>» O uso de hiperlinks facilita a interconexão de informações. Wikis têm diversas aplicações, como</p><p>a famosa Wikipédia.</p><p>» Elas são fáceis de usar, não demandam softwares específicos, e, apesar da edição aberta, podem</p><p>ter uma organização estruturada.</p><p>» As atualizações são em tempo real, favorecendo projetos que necessitam de constantes alterações</p><p>e discussões.</p><p>Figura 58. Wikis.</p><p>Fonte: adaptada pela autora de https://www.canva.com/design/DAFkbxyHzkk/OYdRg9NNb00EJOf5JVypJg/edit?utm_</p><p>content=DAFkbxyHzkk&utm_campaign=designshare&utm_medium=link2&utm_source=sharebutton.</p><p>8</p><p>CAPÍTULO 6 • DOCUMENTAÇÃO DO SISTEMA</p><p>Uma wiki de documentação de software é uma plataforma colaborativa online projetada</p><p>especificamente para criar, organizar e manter documentação relacionada a projetos de</p><p>desenvolvimento de software. Ela atua como um repositório central para todos os tipos de</p><p>documentação associados ao software, incluindo especificações técnicas, guias do usuário,</p><p>documentação de API, diagramas de arquitetura, padrões de codificação e muito mais.</p><p>» Estruturação lógica: organize a documentação de maneira lógica e coerente.</p><p>Divida o conteúdo em seções, capítulos ou tópicos relacionados para facilitar a</p><p>navegação. Uma estrutura bem definida torna a documentação mais acessível</p><p>e ajuda os leitores a encontrar as informações de que precisam.</p><p>» Uso de títulos e sumários: utilize títulos descritivos e sumários para cada seção</p><p>ou tópico. Isso permite que os leitores identifiquem rapidamente os temas</p><p>abordados e naveguem para as partes relevantes da documentação.</p><p>» Clareza e concisão: os textos de uma wiki devem ser redigidos de forma clara</p><p>e concisa. Devem ser evitados jargões técnicos desnecessários, mas é preciso</p><p>fornecer detalhes suficientes para compreensão do que é registrado.</p><p>» Exemplos e ilustrações: inclua exemplos de código, capturas de tela, gráficos</p><p>ou diagramas para ilustrar conceitos complexos. Esses elementos visuais podem</p><p>facilitar a compreensão e tornar a documentação mais atraente.</p><p>» Manutenção contínua: a documentação não é estática e deve ser atualizada à</p><p>medida que o software evolui. Certifique-se de que a documentação acompanhe</p><p>as mudanças no código, novas funcionalidades e correções de bugs. Uma</p><p>documentação desatualizada pode causar muita confusão.</p><p>» Versionamento: assim como o código-fonte, a documentação também pode ser</p><p>versionada. Isso permite que os usuários acessem a documentação relevante</p><p>para a versão específica do software que estão usando.</p><p>» Revisão e feedback: peça revisões e feedback de colegas, membros da equipe e</p><p>outros stakeholders. Isso pode ajudar a identificar áreas de melhoria e garantir</p><p>que a documentação seja clara e compreensível para diferentes públicos.</p><p>» Centralização e acesso: centralize a documentação em um local acessível a todos</p><p>os envolvidos no projeto. É possível recorrer a um sistema de gerenciamento de</p><p>documentos, um sistema de controle de versão ou uma plataforma colaborativa.</p><p>» Manuais de instalação e uso: se o software for destinado a usuários finais, é</p><p>fundamental fornecer manuais de instalação e uso. Esses manuais orientam os</p><p>usuários na configuração e operação adequada do software.</p><p>9</p><p>DOCUMENTAÇÃO DO SISTEMA • CAPÍTULO 6</p><p>Em resumo, a elaboração e a organização da documentação são passos fundamentais</p><p>para garantir que o conhecimento seja compartilhado efetivamente, facilitando a</p><p>compreensão, a colaboração e a manutenção contínua do software. Documentação bem</p><p>estruturada e atualizada contribui significativamente para o sucesso de um projeto de</p><p>desenvolvimento de software.</p><p>6.2 Controle de versão da documentação</p><p>O controle de versão da documentação é um processo fundamental na gestão e</p><p>manutenção de documentos, incluindo todos os tipos de documentação relacionada</p><p>ao desenvolvimento de software. Ele envolve a aplicação de práticas e ferramentas que</p><p>permitem rastrear, controlar e gerenciar as diferentes versões de documentos ao longo</p><p>do tempo. Isso é especialmente importante em ambientes colaborativos, onde várias</p><p>pessoas estão contribuindo para a criação e atualização dos documentos. Alguns dos</p><p>principais aspectos do controle de versão da documentação são discutidos a seguir.</p><p>Rastreamento de alterações</p><p>O controle de versão é uma prática essencial que oferece um nível detalhado de</p><p>rastreamento das alterações realizadas em um documento ao longo do tempo. Ele registra</p><p>meticulosamente todas as edições, desde pequenas correções ortográficas até mudanças</p><p>significativas no conteúdo. Além de simplesmente indicar “quem fez a alteração”, o</p><p>controle de versão também captura informações como a identificação do colaborador</p><p>responsável, sua função ou equipe, e até mesmo comentários que descrevem o propósito</p><p>da alteração. Isso não apenas ajuda a atribuir responsabilidades, mas também proporciona</p><p>um contexto valioso para entender o motivo por trás de cada mudança.</p><p>A marcação temporal também é um componente crucial do rastreamento de alterações.</p><p>Ao saber “quando foi feita a alteração”, os membros da equipe podem identificar o</p><p>cronograma de desenvolvimento, as fases de trabalho e a progressão do projeto. Essa</p><p>informação é vital para sincronizar esforços, acompanhar marcos importantes e gerenciar</p><p>as expectativas dos stakeholders.</p><p>O aspecto mais abrangente do rastreamento de alterações é o detalhamento das</p><p>modificações efetuadas. O controle de versão não apenas registra a adição, remoção ou</p><p>edição de texto, mas também permite uma visualização granular das mudanças linha</p><p>por linha. Isso possibilita uma análise minuciosa de como o conteúdo foi aprimorado,</p><p>permitindo uma compreensão profunda das revisões e facilitando a detecção de possíveis</p><p>erros ou inconsistências.</p><p>10</p><p>CAPÍTULO 6 • DOCUMENTAÇÃO DO SISTEMA</p><p>Quadro 2. Rastreamento de alterações.</p><p>O rastreamento de alterações não é apenas uma função básica do controle de versão, mas uma ferramenta poderosa</p><p>para preservar a história das edições, melhorar a colaboração, facilitar a compreensão das mudanças e garantir a</p><p>transparência em todo o processo de desenvolvimento e revisão da documentação.</p><p>Fonte: elaborada pela autora.</p><p>Versionamento</p><p>Cada alteração em um documento resulta em uma nova versão dele. Esse processo de</p><p>criação de versões ocorre de maneira incremental, à medida que as modificações são</p><p>realizadas. Cada versão é numerada ou identificada de forma única, geralmente com</p><p>um número de versão sequencial, como 1.0, 1.1, 1.2, ou por meio de um sistema de</p><p>identificação alfanumérica, como v1.0.1. Essa abordagem de numeração ou identificação</p><p>única é essencial para distinguir claramente entre as diferentes versões do documento</p><p>e facilitar a referência a versões específicas.</p><p>O processo de versionamento permite acompanhar a evolução do documento ao longo</p><p>do tempo, indicando quais partes foram alteradas, quando essas alterações foram feitas e</p><p>quem as realizou. Isso é particularmente valioso em ambientes colaborativos, onde vários</p><p>membros da equipe podem estar trabalhando no mesmo documento simultaneamente.</p><p>A capacidade de identificar as alterações de maneira granular ajuda a manter o controle</p><p>sobre o progresso do trabalho e a facilitar a revisão e validação das mudanças.</p><p>As versões anteriores do documento são preservadas no histórico, o que permite que os</p><p>usuários comparem versões, restaurem versões anteriores se necessário e compreendam</p><p>como o conteúdo evoluiu ao longo do tempo. Esse histórico detalhado de versões</p><p>é especialmente útil para entender a trajetória de desenvolvimento do documento,</p><p>identificar quando certas informações foram introduzidas ou modificadas e até mesmo</p><p>rastrear a origem de ideias específicas.</p><p>Além disso, a prática de versionamento é essencial para garantir a consistência e a</p><p>confiabilidade da documentação. Quando as alterações são realizadas de maneira</p><p>controlada e registrada, é mais fácil identificar e corrigir eventuais erros ou discrepâncias.</p><p>Além disso, em cenários em que a documentação está sujeita a auditorias ou conformidade</p><p>regulatória, o histórico de versionamento fornece uma trilha de auditoria que demonstra</p><p>as mudanças feitas e os responsáveis por elas.</p><p>Quadro 3. Versionamento.</p><p>O processo de versionamento é um pilar crucial na gestão da documentação, garantindo o controle, a transparência</p><p>e a organização das mudanças ao longo do tempo. Ele apoia a colaboração eficaz, a rastreabilidade das alterações</p><p>e a manutenção da qualidade e integridade da documentação em ambientes de desenvolvimento de software e</p><p>projetos colaborativos.</p><p>Fonte: elaborada pela autora.</p><p>11</p><p>DOCUMENTAÇÃO DO SISTEMA • CAPÍTULO 6</p><p>Revisões e histórico</p><p>Como dito anteriormente, o histórico de versões desempenha papel vital na gestão da</p><p>documentação, pois registra todas as alterações realizadas em um documento desde</p><p>o momento de sua criação. Esse recurso oferece uma visão cronológica detalhada da</p><p>evolução do documento, fornecendo informações sobre quem fez cada alteração, a data</p><p>e a natureza das mudanças realizadas. Por meio desse registro minucioso, os usuários</p><p>têm a capacidade de examinar o desenvolvimento do conteúdo de forma granular,</p><p>observando como a estrutura, o texto e outros elementos foram progressivamente</p><p>refinados, aprimorados e, se necessário, corrigidos ao longo do tempo.</p><p>Essa funcionalidade de histórico é valiosa não apenas para fins de transparência, mas</p><p>também como um recurso para colaboração eficaz. Por exemplo, quando um grupo de</p><p>autores está trabalhando em conjunto, a capacidade de verificar quem contribuiu com</p><p>cada parte do documento, identificar revisões recentes e comparar diferentes versões</p><p>ajuda a evitar conflitos e a manter um registro claro de responsabilidades. Além disso,</p><p>entender as iterações passadas de um documento pode ser essencial para rastrear a</p><p>origem de uma ideia, decidir a direção de um projeto ou até mesmo para fins legais e</p><p>de auditoria.</p><p>À medida que o documento evolui, a capacidade de visualizar as mudanças ao longo</p><p>do tempo facilita a identificação de tendências, melhoria de processos e adaptações às</p><p>necessidades em constante mudança.</p><p>Quadro 4. Revisão e histórico.</p><p>O histórico de versões oferece uma perspectiva enriquecedora sobre a evolução do conteúdo documental,</p><p>fornecendo insights valiosos que podem ser usados para impulsionar a qualidade e a eficiência dos processos de</p><p>criação e manutenção da documentação.</p><p>Fonte: elaborada pela autora.</p><p>Recuperação e reversão</p><p>O controle de versão desempenha papel crucial na recuperação de versões anteriores</p><p>de um documento, oferecendo uma camada de segurança e confiabilidade na gestão</p><p>de alterações. Situações em que uma alteração indesejada, um erro crítico ou uma</p><p>funcionalidade problemática são introduzidos podem ser rapidamente resolvidas com</p><p>a possibilidade de reverter para uma versão anterior. Isso é particularmente valioso em</p><p>cenários em que uma atualização não planejada afeta a estabilidade do software ou a</p><p>integridade dos dados.</p><p>A funcionalidade de recuperação e reversão é viabilizada pela existência de um histórico</p><p>detalhado das versões anteriores do documento. Cada vez que uma edição é realizada,</p><p>12</p><p>CAPÍTULO 6 • DOCUMENTAÇÃO DO SISTEMA</p><p>uma nova versão é criada, preservando o estado anterior. Quando um erro é detectado</p><p>ou uma decisão equivocada é identificada, os responsáveis podem acessar o histórico,</p><p>examinar as versões anteriores e selecionar a versão que corresponde ao estado desejado.</p><p>Isso não apenas permite corrigir erros, mas também oferece uma visão transparente da</p><p>evolução do documento ao longo do tempo. Além disso, a capacidade de revisitar versões</p><p>anteriores é crucial para auditorias, revisões de código, ou mesmo para compreender</p><p>as mudanças que levaram a determinado resultado.</p><p>A reversão a uma versão anterior também é útil quando as alterações atuais não atendem</p><p>aos objetivos ou quando são identificados conflitos com outras partes do projeto. No</p><p>entanto, é importante lembrar que a reversão também deve ser realizada com cuidado,</p><p>pois as informações mais recentes podem ser perdidas, e o processo deve ser coordenado</p><p>para evitar que outros membros da equipe continuem trabalhando com base em</p><p>informações desatualizadas.</p><p>Quadro 5. Recuperação e reversão.</p><p>A capacidade de recuperar e reverter para versões anteriores por meio do controle de versão é uma salvaguarda</p><p>valiosa que não apenas corrige erros, mas também oferece flexibilidade, transparência e segurança no</p><p>gerenciamento de documentos ao longo do ciclo de vida do desenvolvimento de software.</p><p>Fonte: elaborada pela autora.</p><p>Colaboração</p><p>Em ambientes de equipe, várias pessoas com diferentes funções e responsabilidades</p><p>podem colaborar de maneira simultânea em um mesmo documento. Portanto, o controle</p><p>de versão desempenha papel relevante ao permitir que esses colaboradores trabalhem</p><p>de maneira harmoniosa e produtiva. As alterações feitas por cada membro da equipe</p><p>são registradas de forma granular, o que significa que cada adição, modificação ou</p><p>exclusão de conteúdo é detalhadamente documentada. Isso garante a transparência</p><p>nas contribuições e a capacidade de rastrear quem realizou cada uma delas, além de</p><p>quando e por quê.</p><p>Um dos principais desafios enfrentados na colaboração em documentos é evitar</p><p>conflitos e sobreposições indesejadas de edições. O controle de versão resolve essa</p><p>questão, permitindo que múltiplas pessoas editem o mesmo documento sem medo de</p><p>prejudicar o trabalho uns dos outros. Quando duas edições se sobrepõem, o sistema</p><p>de controle de versão é capaz de identificar essas discrepâncias e fornecer ferramentas</p><p>para a resolução de conflitos. Os colaboradores podem revisar as alterações feitas por</p><p>outros membros da equipe, comparar as diferentes versões e decidir quais modificações</p><p>devem ser incorporadas à versão final do documento.</p><p>13</p><p>DOCUMENTAÇÃO DO SISTEMA • CAPÍTULO 6</p><p>Quadro 6. Colaboração.</p><p>O controle de versão viabiliza a colaboração eficiente, organizada e segura, garantindo que as contribuições</p><p>individuais se somem de maneira bem gerenciada. Dessa forma, equipes podem trabalhar em conjunto, mesmo em</p><p>documentos complexos, sem temer conflitos ou dificuldades na integração das edições.</p><p>Fonte: elaborada pela autora.</p><p>Ramos</p><p>Também conhecidos como “branches”, os ramos são uma funcionalidade valiosa oferecida</p><p>por muitas ferramentas de controle de versão. Esse recurso permite que equipes de</p><p>desenvolvimento trabalhem de forma isolada e colaborativa em diferentes aspectos de</p><p>um projeto de software. Quando se trata de documentação, os ramos desempenham</p><p>papel importante na organização e no gerenciamento das alterações e desenvolvimentos</p><p>contínuos e podem oferecer as seguintes vantagens:</p><p>» desenvolvimento paralelo: equipes ou colaboradores podem criar ramos</p><p>específicos para diferentes partes da documentação. Isso é especialmente útil</p><p>quando várias equipes estão trabalhando em funcionalidades distintas que</p><p>exigem atualizações na documentação. Cada equipe pode trabalhar de forma</p><p>independente, sem interferir no progresso das outras;</p><p>» isolamento</p><p>de alterações: os ramos isolam as alterações realizadas por diferentes</p><p>equipes ou colaboradores. Isso evita conflitos diretos e garante que as mudanças</p><p>em uma parte da documentação não interfiram no trabalho em andamento de</p><p>outras áreas;</p><p>» experimentação e testes: ramos permitem que novas ideias sejam testadas sem</p><p>afetar a versão principal da documentação. As equipes podem experimentar</p><p>novos formatos, estruturas ou conteúdos sem comprometer o trabalho existente;</p><p>» gerenciamento de versões: cada ramificação gera uma sequência própria de</p><p>versões, permitindo um histórico de alterações independente. Isso ajuda a</p><p>controlar o desenvolvimento específico de cada área e facilita a revisão e auditoria</p><p>de mudanças;</p><p>» implementação gradual: se a documentação precisa ser atualizada em etapas,</p><p>os ramos possibilitam a implementação gradual das mudanças em diferentes</p><p>momentos. Isso é útil quando as atualizações precisam ser liberadas em sincronia</p><p>com o progresso do software;</p><p>» colaboração eficiente: ramos permitem que diferentes partes da equipe trabalhem</p><p>em paralelo, o que agiliza o desenvolvimento e aumenta a eficiência. Cada equipe</p><p>pode se concentrar em suas tarefas específicas sem interrupções.</p><p>14</p><p>CAPÍTULO 6 • DOCUMENTAÇÃO DO SISTEMA</p><p>» minimização de conflitos: à medida que as equipes finalizam suas alterações</p><p>em seus ramos, as chances de conflitos ao mesclar essas mudanças na versão</p><p>principal são reduzidas. Isso ocorre porque as alterações já foram revisadas em</p><p>seus respectivos ramos.</p><p>Quadro 7. Ramos.</p><p>Os ramos são uma ferramenta valiosa para gerenciar o desenvolvimento da documentação de maneira mais</p><p>eficiente e organizada. Eles permitem que equipes trabalhem em paralelo, experimentem novas abordagens</p><p>e controlem o desenvolvimento de partes específicas da documentação sem comprometer a integridade do</p><p>projeto global.</p><p>Fonte: elaborada pela autora.</p><p>Integração com ferramentas</p><p>O controle de versão da documentação pode ser integrado de maneira estreita e eficiente a</p><p>diversas outras ferramentas amplamente utilizadas no desenvolvimento de software. Essa</p><p>integração proporciona uma sinergia valiosa ao conectar a documentação diretamente</p><p>ao processo de desenvolvimento e colaboração. Algumas das formas mais relevantes de</p><p>integração incluem:</p><p>» sistemas de gerenciamento de projetos: ao vincular o controle de versão da</p><p>documentação aos sistemas de gerenciamento de projetos, os membros da</p><p>equipe podem associar documentos a tarefas, marcos e histórico de atividades.</p><p>Isso permite um acompanhamento detalhado do progresso, assegurando que</p><p>cada atualização na documentação esteja alinhada às atividades planejadas;</p><p>» plataformas de colaboração: a integração com plataformas de colaboração,</p><p>como Slack, Microsoft Teams ou outras ferramentas de comunicação, torna</p><p>possível receber notificações automáticas sobre atualizações na documentação.</p><p>Essa conexão em tempo real mantém a equipe informada e facilita a discussão</p><p>sobre as mudanças realizadas;</p><p>» ferramentas de desenvolvimento: muitas vezes, a documentação está diretamente</p><p>relacionada ao código-fonte e às funcionalidades implementadas. Integrar o</p><p>controle de versão da documentação com as ferramentas de desenvolvimento,</p><p>como sistemas de controle de versão de código (como o Git) ou sistemas de</p><p>rastreamento de problemas, permite que as mudanças na documentação estejam</p><p>em sintonia com as alterações no código;</p><p>» ambientes de desenvolvimento: alguns ambientes de desenvolvimento (IDEs)</p><p>possuem integração com sistemas de controle de versão da documentação. Isso</p><p>pode simplificar o processo de edição e atualização da documentação diretamente</p><p>dentro da IDE, permitindo que os desenvolvedores mantenham a documentação</p><p>atualizada sem sair do ambiente de trabalho;</p><p>15</p><p>DOCUMENTAÇÃO DO SISTEMA • CAPÍTULO 6</p><p>» automação de fluxos de trabalho: a integração também pode ser usada para</p><p>automatizar fluxos de trabalho. Por exemplo, ao finalizar uma tarefa específica</p><p>no sistema de gerenciamento de projetos, uma ação automatizada pode atualizar</p><p>automaticamente a documentação relevante ou criar uma entrada de registro</p><p>correspondente;</p><p>» ferramentas de revisão e aprovação: integrar o controle de versão da documentação</p><p>com ferramentas de revisão e aprovação facilita o processo de coleta de feedback</p><p>e garantia de qualidade. As alterações na documentação podem ser revisadas</p><p>por membros da equipe ou stakeholders antes de serem consolidadas;</p><p>» geração de relatórios: a integração com ferramentas de geração de relatórios</p><p>pode permitir a criação automatizada de relatórios sobre as mudanças na</p><p>documentação, auxiliando na auditoria, revisão e acompanhamento das atividades.</p><p>Quadro 8. Integração com ferramentas.</p><p>A integração do controle de versão com outras ferramentas oferece uma abordagem holística ao desenvolvimento</p><p>de software, na qual os documentos são interconectados e alinhados aos diferentes aspectos do projeto. Isso traz</p><p>colaboração mais eficiente, melhoria na qualidade e alinhamento dos esforços de desenvolvimento.</p><p>Fonte: elaborada pela autora.</p><p>Acompanhamento de alterações</p><p>Além das alterações no conteúdo, é possível associar comentários e notas a cada versão,</p><p>permitindo um registro mais detalhado do raciocínio por trás de cada modificação.</p><p>Esses comentários e notas podem variar desde explicações sobre a correção de um</p><p>bug específico, sugestões de melhoria, descrição de novos recursos ou funcionalidades</p><p>adicionadas, até insights sobre a resolução de problemas técnicos.</p><p>Essa prática de adicionar comentários contextualiza as mudanças realizadas, o que</p><p>é especialmente valioso quando várias pessoas colaboram no mesmo documento.</p><p>Os comentários podem esclarecer o porquê de uma alteração específica, indicar se a</p><p>modificação está relacionada a requisitos específicos, destacar preocupações de segurança</p><p>ou desempenho, ou mesmo detalhar os resultados de testes realizados naquela versão.</p><p>Ao longo do tempo, essa documentação adicional de comentários e notas não apenas</p><p>ajuda os membros da equipe a compreender o histórico de evolução do documento,</p><p>mas também facilita a resolução de conflitos e a tomada de decisões baseada em</p><p>evidências. Por exemplo, se houver um debate sobre a melhor abordagem para</p><p>determinado aspecto, os comentários podem fornecer ideias sobre as considerações</p><p>que levaram a determinada escolha.</p><p>16</p><p>CAPÍTULO 6 • DOCUMENTAÇÃO DO SISTEMA</p><p>Além disso, a presença de comentários detalhados também ajuda no treinamento de novos</p><p>membros da equipe. Eles podem aprender com as explicações de decisões anteriores e</p><p>compreender o contexto por trás das escolhas de design e implementação.</p><p>Quadro 9. Acompanhamento de alterações.</p><p>No geral, o recurso de adicionar comentários e notas a cada versão não apenas enriquece o registro do processo</p><p>de desenvolvimento, mas também aprimora a comunicação, o compartilhamento de conhecimento e a colaboração</p><p>dentro da equipe, contribuindo para um controle de versão mais informativo e eficaz.</p><p>Fonte: elaborada pela autora.</p><p>Segurança e privacidade</p><p>Em algumas plataformas de controle de versão da documentação, é possível definir</p><p>permissões de acesso altamente granulares para diferentes usuários ou grupos. Essa</p><p>capacidade permite um controle preciso sobre quem pode editar, visualizar ou até</p><p>mesmo comentar em documentos específicos. As permissões podem ser ajustadas em</p><p>nível de página, seção ou até mesmo para partes específicas de um documento. Isso é</p><p>particularmente valioso em cenários em que determinadas informações são sensíveis ou</p><p>confidenciais, como dados pessoais, informações proprietárias ou estratégias comerciais.</p><p>Além disso, algumas plataformas oferecem recursos avançados de auditoria, que registram</p><p>todas as atividades relacionadas a um documento, incluindo quem visualizou, editou ou</p><p>fez alterações. Isso cria um percurso completo de auditoria, garantindo a transparência</p><p>e a capacidade de rastrear todas as interações com os documentos.</p><p>Outro aspecto importante é a integração</p><p>com sistemas de autenticação e Single Sign-On</p><p>(SSO), que permitem que as mesmas credenciais de login usadas em outros sistemas</p><p>sejam usadas para acessar a documentação. Isso simplifica o gerenciamento de contas</p><p>e ajuda a manter alto nível de segurança.</p><p>Em cenários mais complexos, como projetos que envolvem colaboradores externos ou</p><p>parceiros, algumas plataformas de controle de versão permitem o compartilhamento</p><p>seguro de documentos por meio de links com prazo de validade. Essa possibilidade</p><p>garante que as informações sejam compartilhadas apenas por um período específico e,</p><p>após esse prazo, o acesso é automaticamente revogado.</p><p>Quadro 10. Segurança e privacidade.</p><p>As funcionalidades de segurança e privacidade nas plataformas de controle de versão da documentação são</p><p>essenciais para garantir que informações confidenciais sejam protegidas, que as edições sejam controladas e que as</p><p>atividades sejam registradas de maneira transparente, contribuindo para a segurança geral da documentação e do</p><p>processo de desenvolvimento.</p><p>Fonte: elaborada pela autora.</p><p>17</p><p>DOCUMENTAÇÃO DO SISTEMA • CAPÍTULO 6</p><p>O controle de versão da documentação é uma prática fundamental para garantir a</p><p>integridade, colaboração eficaz e gestão adequada da evolução dos documentos ao longo</p><p>do ciclo de vida do desenvolvimento de software. Isso ajuda a preservar o histórico das</p><p>mudanças, simplificar processos de revisão e garantir a qualidade e consistência da</p><p>documentação ao longo do tempo.</p><p>O que vimos neste capítulo?</p><p>» A documentação do sistema refere-se ao conjunto de materiais redigidos e artefatos construídos</p><p>que fornecem informações sobre um software.</p><p>» A documentação pode incluir manuais do usuário, tutoriais, guias, perguntas frequentes e</p><p>quaisquer recursos que ajudem os usuários a navegar pelo aplicativo.</p><p>» A elaboração e a organização da documentação contribuem para uma comunicação e colaboração</p><p>eficazes e manutenção do software ao longo do tempo.</p><p>» O controle de versão da documentação envolve a aplicação de práticas e ferramentas que</p><p>permitem rastrear, controlar e gerenciar as diferentes versões de documentos ao longo do tempo.</p><p>18</p><p>Referências</p><p>GUEDES, Gilleanes T. A. UML 2: uma abordagem prática. 3. ed. São Paulo: Novatec, 2018.</p><p>SOMMERVILLE, Ian. Engenharia de software. 10. ed. São Paulo: Pearson, 2015.</p><p>Imagens</p><p>AZQUOTES. Linus Torvalds: Criador do Sistema Git. (Adaptada). Disponível em: https://www.azquotes.com/</p><p>quote/296071. Acesso em: 12 jul. 2023.</p><p>FIGMA. Figma: the collaborative interface design tool. Disponível em: https://www.figma.com/. Acesso em: 9 jun. 2023.</p><p>FREEPIK. Disponível em: https://img.freepik.com/free-vector/hand-drawn-flat-design-devops-</p><p>illustration_23-2149383352.jpg?w=996&t=st=1689344063~exp=1689344663~hmac=a11ede13f2aa53df1a598b16379c</p><p>35a9213fe9961ed9b75927cb1092e3ca1621. Acesso em: 12 jul. 2023.</p><p>FREEPIK. Disponível em: https://br.freepik.com/vetores-gratis/varias-telas-para-aplicativo-movel-violeta-de-</p><p>transporte-publico_10504567.htm#query=user%20interface%20mockup&position=30&from_view=search&track=ais.</p><p>Acesso em: 6 set. 2023.</p><p>FREEPIK. Disponível em: https://br.freepik.com/vetores-gratis/ilustracao-do-modelo-de-design-da-web_3139740.</p><p>htm#query=low%20fidelity%20wireframe&position=0&from_view=search&track=ai. Acesso em: 6 set. 2023.</p><p>FREEPIK. Disponível em: https://br.freepik.com/vetores-gratis/ilustracao-de-devops-de-design-plano-desenhado-a-</p><p>mao_25632088.htm#query=hand-drawn-flat-design-devops-illustration&position=5&from_view=search&track=sph.</p><p>Acesso em: 6 set. 2023.</p><p>QATESTLAB. Relação Desenvolvedor x Testador. Testers and Developers: Together in Sorrow and Joy. Disponível em:</p><p>https://blog.qatestlab.com/2016/07/29/testers-developers-together/. Acesso em: 12 jul. 2023.</p><p>SKETCHING DEVELOPER. Disponível em: https://sketchingdev.co.uk/sketchnotes/testing-pyramid.html. Acesso</p><p>em: 6 set. 2023.</p><p>_Hlk148446329</p>