Technical Writing: crie uma documentação do zero com DDLC

Iniciando seu processo de documentação - Apresentação

Olá! Boas-vindas ao segundo curso da formação de Technical Writing (Escrita Técnica) da Alura! Sou a Mari Moreira, instrutora da Escola de UX Design, e será um prazer ter você comigo.

Audiodescrição: Mari se autodescreve como uma mulher branca, de cabelos castanho-escuros, levemente ondulados. Seus olhos também são castanho-escuros. Está usando um vestido preto de mangas. Ao fundo, há um cenário da Alura com alguns objetos de decoração e iluminação roxa.

Objetivo do curso

O objetivo do curso é oferecer todas as ferramentas necessárias para que você consiga se aprofundar no Technical Writing e conheça um processo de documentação do zero. Para isso, vamos usar um framework bastante conhecido no mercado, que se chama DDLC.

Entenderemos o que o DDLC é e passaremos por cada uma das fases desse processo atrelado ao nosso projeto do curso, que será justamente criar uma documentação do início dentro de uma plataforma de documentação, o Gitbook.

O Gitbook é uma plataforma gratuita. Nela, criaremos uma conta, iniciaremos um projeto e geraremos uma documentação.

Público-alvo

Este curso foi pensado para todas as pessoas do mercado de tecnologia que já atuam com o desenvolvimento de software ou que estão inseridas no ecossistema de tecnologia em outras carreiras, mas que, de alguma forma, têm envolvimento com documentação técnica no dia a dia e que, acima de tudo, desejam aprofundar seus conhecimentos e entender como trabalhar a documentação técnica com um processo de uma ponta a outra.

Esperamos que você tenha gostado! Não se esqueça de participar do Fórum ou do canal do Discord da Alura. Com certeza, sua contribuição na comunidade será valiosíssima!

Te espero no curso. Até!

Iniciando seu processo de documentação - Apresentação do projeto do curso

Vamos falar sobre o projeto do curso? Ele é um pouco diferente do que foi proposto no curso 1 da formação de Technical Writing, onde a proposta era criar um repositório de documentações utilizando o GitHub.

Dessa vez, faremos de uma forma distinta. Nosso objetivo é aprofundar nossos conhecimentos em Technical Writing (Escrita Técnica) e entregar uma documentação técnica em uma plataforma com aparência de site.

Entendendo o projeto

Na tela, estamos visualizando como seria usar o Gitbook, ferramenta proposta neste curso, para gerar uma documentação para o ByteBank. Neste projeto, seremos novamente o TechWriter (Escritor Técnico) do ByteBank, porém o processo para chegarmos às documentações será diferente.

Vamos seguir o processo de documentação do zero, desde o planejamento até a criação, revisão e publicação dentro do Gitbook.

Durante o curso, teremos vídeos para aprender a configurar o Gitbook, formatar visualmente, mudar a cor, adicionar logo, etc. Mas neste vídeo, nossa intenção é entender a aparência do Gitbook e como criar uma conta nele, lembrando que a criação de conta é gratuita. O Gitbook tem uma versão paga, mas para o propósito deste curso, não é necessário adiquirí-la.

Apresentando rapidamente, nosso cursor está no topo, no canto superior esquerdo, onde está o logo da ByteBank. No canto superior direto, temos o campo de busca. Temos, inclusive, a opção de escolher light ou dark mode para a tela (modo claro e escuro). Também conseguimos adicionar menu e submenu, criando um menu interativo como em um site.

Como criar a conta no Gitbook? Primeiro, vamos acessar o site do Gitbook. A página inicial mostra como funciona a plataforma, mas nosso foco agora é especificamente a criação de conta. No canto superior direito, existem duas opções: "Start for free" (comece de graça) ou "Login" (entrar). Como ainda não temos conta, vamos selecionar "Start for free".

Ao fazer isso, seremos redirecionados para a página de criação de conta. Nessa página, temos algumas opções. Podemos "continuar com o GitHub". Inclusive, é interessante destacar que o Gitbook permite integração com várias ferramentas, inclusive o próprio GitHub.

Caso você trabalhe em uma empresa que tem um repositório com vários códigos e conteúdos técnicos e deseja integrar o seu Github ao Gitbook, você pode fazer isso. Esta é uma das opções.

Outra opção é, se tiver conta no Gmail, você pode continuar com a conta do Gmail. Caso não tenha nenhuma dessas opções, basta fazer o cadastro, Sign up, usando e-mail.

Depois de preencher o e-mail e continuar, será necessário preencher uma série de informações, como senha, etc. Em seguida, aparecerá uma tela inicial, onde precisaremos criar uma organização (organization).

Não se preocupe com isso agora, pois teremos um vídeo mais adiante no curso para discutir sobre como criar uma organização e fazer as primeiras configurações no Gitbook para o site, isto é, para o portal da sua documentação ir ganhando forma e criando uma aparência, assim como a documentação final que mostramos no início do vídeo.

No próximo vídeo, falaremos sobre o DDLC (Framework de Processo de Documentação), que norteará a construção do nosso projeto. Nos encontramos no próximo vídeo. Até mais.

Iniciando seu processo de documentação - O que é o Ciclo de Vida de Desenvolvimento de Documentação (DDLC)?

A partir de agora, vamos nos aprofundar no processo de documentação partindo do zero. Com isso, ganharemos mais conhecimento e propriedade na construção de nossas documentações como pessoa TechWriter.

A ideia do curso é detalhar cada uma das etapas. Porém, antes, precisamos entender qual é o framework de processo que utilizaremos, o DDLC, sigla para — em uma tradução livre do inglês — Ciclo de Vida de Desenvolvimento da Documentação.

Portanto, adiantando os objetivos, a ideia deste vídeo, em um primeiro momento, é entender o que é o DDLC e, conhecer, brevemente, as etapas que compõem esse framework de processo de documentação. Lembrando que teremos vídeos dedicados a cada um desses processos ao longo do curso.

DDLC

Em uma explicação muito rápida, o DDLC é chamado de Ciclo de Vida da Documentação por ter uma abordagem semelhante a outro framework bastante conhecido por quem trabalha com desenvolvimento, que é o Ciclo de Vida de Desenvolvimento do Software.

De uma forma muito resumida, podemos dizer que duas principais características que o DDLC prega são: independentemente das adaptações feitas na empresa onde trabalhamos, o processo deve ser sistemático e também cíclico.

Isso porque, acima de tudo, o principal objetivo é garantir protagonismo para a documentação nos processos de trabalho de uma maneira que ela seja constantemente criada e atualizada.

Pensando nas etapas do processo, podemos dizer que o DDLC é composto por seis etapas. São elas:

1 - Análise e planejamento, quando começamos o trabalho de planejamento dessa documentação ou desse conjunto de documentações que queremos criar;

2 - Design ou estruturação da documentação;

3 - Desenvolvimento do conteúdo ou escrita, que é quando começamos a desenvolver a documentação;

4 - Edição e revisão, comumente chamada de proofreading no inglês, que é exatamente o processo de ler e validar se o que está escrito atende ao que foi definido no planejamento;

5 - Publicação;

6 - Manutenção, etapa fundamental e que reforça o caráter cíclico do processo. Ou seja, após passar por todo o ciclo de desenvolvimento, precisamos garantir que ele será mantido e escalável.

Conclusão e próximos passos

O que você achou do DDLC? Quero saber a sua opinião no fórum ou no Discord. Nos encontramos no próximo vídeo, em que vamos para a primeira etapa, de análise e planejamento da documentação, principalmente pensando no nosso projeto do Gitbook. Combinado?

Te espero no próximo vídeo. Até lá.

Sobre o curso Technical Writing: crie uma documentação do zero com DDLC

O curso Technical Writing: crie uma documentação do zero com DDLC possui 119 minutos de vídeos, em um total de 42 atividades. Gostou? Conheça nossos outros cursos de UX Writing em UX & Design, ou leia nossos artigos de UX & Design.

Matricule-se e comece a estudar com a gente hoje! Conheça outros tópicos abordados durante o curso:

• Iniciando seu processo de documentação
• Estruturando sua documentação
• Escrita e revisão
• Publicação
• Medindo a eficácia da sua documentação