Embora a segunda reunião do Write the Docs Moscow tenha ocorrido há um mês, nunca é tarde para publicar um relatório e resumos curtos dos relatórios. Conseguimos discutir praticamente tudo: da documentação de uma API RESTful às trajetórias profissionais de um escritor técnico.
O Mitap, a propósito, reuniu não apenas o “gueto técnico”, mas também uma ampla gama de outros especialistas que trabalham de uma maneira ou de outra com a documentação do projeto: líderes de equipe, analistas, testadores e até um diretor técnico.
Nossa
reunião ocorreu no dia 14 de outubro , domingo (ele entrou no topo das perguntas mais populares sobre ele, “Por que no domingo?”) No escritório do IPONWEB. Os comícios Write the Docs são realizados em todo o mundo, de Bangalore a São Francisco, de Londres a Seul, a filial russa da comunidade está apenas ganhando atividade, mas já existem filiais em Moscou, São Petersburgo e Novosibirsk.
Anton Telin, Por que e como fazemos as instruções em vídeoVídeoSlidesAnton gerencia o departamento de documentação técnica da VLSI, que fabrica um sistema de gerenciamento eletrônico de documentos. Por que um vídeo? As pessoas não querem ler instruções, querem resolver um problema. As pessoas querem ser clara e claramente explicadas a elas.
O vídeo é uma maneira conveniente de apresentar uma grande quantidade de informações, implementar um script em dinâmica, uma sequência de ações. Você também pode acentuar a atenção do usuário com música ou dublagem.
Se o produto é complexo e não possui uma interface bem pensada, sem a parte visual é difícil transmitir sua essência ao usuário. A vantagem é que reduz o custo do suporte técnico.
Contras - não é adequado para todos os formatos de publicação, é difícil incorporar em doc e pdf. É difícil pesquisar. Vídeos de alta qualidade são mais caros.
Outro problema urgente é a complexidade da atualização, mas a campanha de Anton resolveu esse problema. Eles se recusaram a gravar screencasts (capturas de tela) em favor de capturas de tela de alta qualidade.
A empresa usa dois formatos de vídeo:
1. A instrução em vídeo é uma sequência de ações, em detalhes e em etapas. Duração ~ 2 minutos. 1 instrução é 1 problema. Ele não fala sobre todas as janelas, gralhas, botões. Adicionou dublagem, música de fundo, explicações de texto, legendas.
2. Vídeo explicativo. Isso é algo na junção das instruções e apresentações do produto. Uma visão geral sem detalhes técnicos resolve vários problemas ou cenários. Este vídeo pode incluir pessoas e animação. Duração 2-3 minutos.
Ferramentas: Adobe Premiere e Adobe After Effect para edição, Adobe Audition para som, Photoshop e Snagit para edição de imagens. O projeto é montado a partir de uma variedade de capturas de tela, que não são relevantes ou incorretas, e é fácil substituí-las. Em seguida, desenhando o movimento do mouse, animação, som.
Eles decidiram usar anunciadores não profissionais para o trabalho de voz, pois pareciam muito formais; portanto, usam a voz de um funcionário da empresa Ilya, que canta em um grupo de metalcore. Após um bloco de informações, é necessária uma pausa de 2 segundos para a compreensão.
Os vídeos são publicados em sua própria hospedagem e no Youtube. A desvantagem é bloqueá-lo por muitas empresas por razões de segurança.
Obviamente, o VLSI coleta todas as estatísticas disponíveis: tempo médio de visualização, curtidas, chamadas de suporte técnico que foram fechadas usando o link de vídeo.
Nikolay Volynkin, escritor técnico versão 2.0.1VídeoSlidesEsta é uma repetição, ou melhor, um complemento ao relatório da conferência SECR. Nikolai assistiu a escritores técnicos por um longo tempo e percebeu que nem sempre eles sabem como justificar e medir seus benefícios, e os líderes que os definem também.
Existem algumas tarefas relacionadas que os escritores técnicos poderiam resolver. Nikolay disse que trajetórias de carreira e conjuntos de habilidades têm descrições técnicas, como vender suas novas tarefas para os negócios.
5 papéis que um escritor técnico pode desempenhar:
1.
Docops - devops para documentação, um escritor / programador, ele pode automatizar a geração, verificação, upload de documentação, treina a equipe para trabalhar com ela e reconstrói todos os processos ao seu redor.
Os benefícios são redução da mão-de-obra manual, economia de recursos e velocidades de entrega de recursos maiores.
2.
UX writer - especialista em escrever textos em interfaces.
Benefícios - designers, poemas, analistas ou desenvolvedores de front-end nem sempre entendem como escrever corretamente, como transmitir funções, botões, transições para um usuário. Os textos são escritos de acordo com o princípio de quem primeiro se levantou e chinelos. Conveniência da interface, reduzindo o tempo para suporte técnico.
3. Um
evangelista técnico , ele fala sobre tecnologia, interage com a comunidade, molda-a.
Benefícios - aumento da confiança e lealdade à empresa, ao produto, simplificação de contratação, marca de RH.
4.
Gerente de conhecimento - explora como uma empresa produz, armazena e transfere conhecimento. Estabelece esses processos para que o conhecimento não vaze.
Benefícios - fator de ônibus reduzido, velocidade de adaptação dos funcionários, tanto iniciantes quanto durante as transições internas, reutilização de conhecimento, redução de riscos.
5.
Proprietário da documentação - PM e analista de documentação. Ele constrói todo o sistema de comunicação e interação do usuário na documentação.
O benefício está novamente na redução dos custos de suporte.
Durante a discussão, lembramos de um papel tão integrado como gerente de conteúdo, que não foi mencionado no relatório.
Konstantin Valeev, FoliantVídeoSlidesConstantine da Restrim falou sobre a ferramenta
Foliant - a implementação do fluxo de trabalho docops baseado na linguagem Markdown. Há um ano, como parte do
mini-Hyperbaton em Yandex, Konstantin já falava sobre Foliant, e muita coisa mudou desde então.
A documentação está escrita em arquivos MD e, em diferentes locais, a ferramenta suporta integração contínua, montagem automática e também permite expandir o MD ao seu gosto.
Requisitos: você precisa fornecer docx para clientes e PDF com boa tipografia, ter fontes legíveis por humanos (não XML).
Sob o capô, um conversor Pandoc universal é usado, Python, scripts bash são enrolados no topo. Porém, com o tempo, o número de scripts aumentou e, portanto, foram reescritos em um único aplicativo monolítico.
A partir do monólito, eles criaram uma estrutura modular com o núcleo controlando a montagem, pré-processadores que convertem o MD para o trabalho dos montadores e os próprios montadores.
Foliant é essencialmente a cola entre boas ferramentas (mkdoc, pandoc, slate, latex). Agora eles estão tentando ensinar como consumir fontes de documentação de diferentes formatos.
Na pasta do projeto, há uma configuração com a estrutura do documento final, estilos e arquivos de MD reais. Em seguida, os pré-processadores pegam os arquivos de MD de origem e aplicam o processamento a eles para criar o MD desejado no estilo de all.md (md no estilo de foliant) e, em seguida, coletores dos documentos finais ( pandoc, mkdoc) os tornam alvos (documentos). Após a montagem do MD, os linters são executados para verificar a sintaxe. As notificações de compilação sobre compilações ou bugs também são enviadas.
Tudo isso pode ser coletado no Docker, para que todos os pacotes sejam entregues de uma maneira, e não cada um separadamente.
O Foliant suporta avançados incluem, pode extrair trechos de código do Gitlab / Github e imagens com layouts do Simpli, pode desenhar diagramas, substituir parâmetros no texto, instruções condicionais.
Nikita Samokhvalov, Documentação abrangente sobre a API RESTfulVídeoSlidesNikita Samokhvalov, diretora técnica da Notamed, contou como eles configuraram a geração de documentação da API com base no Open API 3.0.
Como todo mundo, eles começaram com o Google Docs, mas ele não possui controle de versão nem capacidade de criar ramificações. Então eles começaram a escrever arquivos MD no repositório, o problema de criação de versões e criação de ramificações foi resolvido, mas tudo ficou lento. Depois veio a geração automática.
A documentação tinha os seguintes requisitos: herança e reutilização de partes da documentação, capacidade de fornecer um link para descrições de parâmetros e métodos, informações sobre a diferenciação de direitos de acesso, documentação como um código (implantações e alterações síncronas). Além disso, a documentação não é publicada publicamente, apenas para sua equipe e equipes de desenvolvimento de pós-graduação.
Escolhemos a especificação OpenAPI 3.0. Porque É o mais recente, suporta mais recursos, embora ainda exista um pequeno ecossistema e experiência em torno dele.
Eles pegaram a ferramenta
shins (mostra arquivos MD em uma linda página de destino com exemplos de consultas, descrição de métodos, parâmetros),
widdershins (conversor yaml / json para MD), eles também escreveram seu próprio pacote
specker (instala todas as dependências necessárias, funciona através do npm, também verifica a correção da estrutura de alocação de arquivos).
A configuração do ambiente e a documentação da montagem são feitas em uma única linha no console. Os arquivos que precisam ser reutilizados em cada projeto, por exemplo, uma descrição de autorização, caem na pasta dependências /.
Nikita também falou sobre como eles trabalham com filiais em uma equipe distribuída, quando a tarefa é atualizar a documentação e, é claro, sobre as armadilhas e dificuldades que acompanharam a implementação do OpenAPI 3.0.
Svetlana Novikova, Gerenciamento de conhecimento usando a matriz de competênciasVídeoSlidesSvetlana (a propósito, este sou eu) falou sobre como eles na empresa organizaram uma reinicialização do instrumento de ponta a ponta da esfera de gerenciamento de pessoal como uma matriz de competências, qual é o uso da gestão de conhecimento dessa maneira, como o instrumento ajuda a reduzir o fator de ônibus, é melhor abordar os recém-chegados e até encontrar peças código para refatoração.
Danila Medvedev, NeuroCodeVídeoDanila falou sobre uma ferramenta que é compreensível para todos, e talvez à frente de nosso tempo, para modelar e armazenar conhecimento chamado NeuroCode.
Essa ferramenta é útil para qualquer pessoa envolvida no design de sistemas de TI. Em particular, Danila sugere abandonar os sistemas baseados em documentos. Qualquer sistema é considerado como uma rede, de acordo com os nós dos quais algumas informações são transmitidas. Todos os elementos do sistema obedecem a esse princípio - atualizações push, transferência de documentos, transferência de feedback. O objetivo do NeuroCode é "reduzir custos improdutivos para apoiar processos e fortalecer a inteligência coletiva da organização".
O projeto NeuroCode surgiu da solução do problema - como criar um bom repositório de informações para uma equipe ou para você, como criar um modelo de informação. O protótipo do sistema é feito e funciona, agora está sendo testado com a ajuda de engenheiros de sistema e arquitetos de negócios. O sistema possui uma interface escalável e é baseado em uma estrutura de dados fractal. Também se baseia nas idéias de Douglas Engelbart (este é um dos primeiros pesquisadores da interface homem-máquina, autor dos conceitos de GUI, hipertexto etc.) da década de 1960 sobre Open Hyper-Document Systems (OHS), quando o sistema não é baseado em documentos, mas um único isto é, implementa todos os processos da atividade humana.
PS Em geral, é melhor assistir ao vídeo.
A próxima reunião,
Write the Docs Moscow, será realizada no dia 7 de dezembro, no escritório da Positive Technologies, e será realizada no formato de Positive Authoring Tools Battle.
