O MS Word nos lança regularmente “surpresas”: capturas de tela “removidas”, tabelas “flutuantes”, páginas em branco durante a impressão. Este artigo é sobre como estávamos procurando um substituto para o MS Word (não encontramos um spoiler), mas encontrou uma oportunidade para melhorar nosso processo de trabalhar com a documentação globalmente.
Na Uniscan Research, transformamos produtos de alta tecnologia em produtos seriais. A empresa atua nos setores B2G (empresa para governo) e B2C (empresa para cliente).
Nosso departamento desenvolve design e documentação do usuário para produtos em desenvolvimento, documentos de certificação, materiais de marketing, design e decoração de escritórios (navegação, sinalização de portas).
Com documentos no setor B2C, há liberdade para escolher o formato, nome e conteúdo da documentação. No setor B2G, cerca de 70% da documentação que desenvolvemos deve ser preparada de acordo com os requisitos da ESKD e submetida à aprovação do cliente no formato DOCX.
Transmitimos ao usuário toda a documentação operacional em formato impresso, para que todos os documentos sejam submetidos à preparação pré-impressão. Nossos documentos têm dois formatos de destino: DOCX e PDF.
Para a implementação de nossas tarefas, o departamento tradicionalmente usa o MS Word há muitos anos.
A cada nova edição de um documento compilado no MS Word, em cerca de metade dos casos as capturas de tela "deslizam", as tabelas com ícones "flutuam" e, quando um documento é impresso, as páginas em branco invisíveis aparecem completamente. Essas operações de layout de documento afastam o autor do documento, não apenas no tempo, mas também no desejo de se engajar na criatividade - o desenvolvimento de novos documentos.
Durante a próxima pesquisa de páginas em branco invisíveis em um documento DOCX em nosso departamento, surgiu a idéia de experimentar uma nova ferramenta de desenvolvimento de documentação. Queríamos reduzir o tempo de layout e pré-impressão do documento.
Como resultado, não conseguimos nos livrar completamente do uso do MS Word, mas no processo de pesquisa, criamos um novo esquema para trabalhar com a documentação.
Em seguida, tentarei explicar quais ferramentas para trabalhar com os documentos que consideramos, por que decidimos usar o Confluence como resultado, quais problemas encontramos e como fomos capazes de resolvê-los.
Seleção de ferramenta
Lemos artigos sobre o tópico das ferramentas de desenvolvimento de documentação existentes, conversamos com colegas de outras empresas. As seguintes ferramentas nos pareciam mais adequadas:
- Dita
- DocBook XML
- Confluência
As duas primeiras ferramentas não se encaixavam pelo mesmo motivo: precisávamos de habilidades de programação que não tínhamos e, para criar um novo modelo de documento, precisaríamos pedir ajuda de um programador. A transição para trabalhar com eles, de acordo com nossas idéias, levaria cerca de seis meses, possivelmente mais. Devido às desvantagens acima, decidimos abandonar o teste completo dessas ferramentas.
A confluência desde o início agradou o editor
WYSIWYG . Em média, os redatores técnicos levaram cerca de uma semana para dominar a ferramenta; o layout dos documentos "em desacordo com o GOST" era mais fácil.
Nos projetos B2G, o PDF é importante para nós como um formato para a documentação do usuário. Portanto, instalamos imediatamente o plug-in apropriado para o Confluence - Scroll PDF Exporter. Com isso, tentamos criar modelos personalizados com os parâmetros necessários. Ficamos satisfeitos com os resultados do teste: criamos um dos documentos com um grande número de capturas de tela e elementos gráficos no MS Word por cerca de uma semana; em Confluence, conseguimos distribuir o mesmo documento em 2 dias e obter uma melhor apresentação visual.
Também tentamos configurar o modelo para o Scroll Word Exporter de forma a obter um documento emitido de acordo com todas as regras ESKD. Após dois dias de leitura dos guias Confluence e Scroll PDF Exporter e tentando personalizar o modelo atual de especificações técnicas, percebemos que essa ferramenta não é adequada para o desenvolvimento de documentos executados de acordo com os requisitos da ESKD.
Assim, por exemplo, não conseguimos criar títulos não gordurosos numerados do segundo nível para que o texto não fosse um título, mas um parágrafo. Eu tive que escrever manualmente o número do parágrafo e usar o estilo do parágrafo. Era impossível organizar listas com marcadores com um traço (apenas círculos, quadrados), as listas numeradas eram desenhadas sem um ponto e as listas de letras eram apenas com letras latinas. O recuo foi ajustado apenas manualmente.
Alguns meses depois que começamos a dominar o Confluence, os desenvolvedores da ferramenta implementaram a função de editar documentos em seu formato original. Isso nos permitiu armazenar nossos documentos "convidados" e criar novos documentos que não exigem execução estrita no mesmo local. Os arquivos do MS Word são armazenados no Confluence como anexos, quando editados, são abertos e salvos no MS Word no PC do usuário e, ao salvar, a nova versão é automaticamente carregada no Confluence.
Então, tivemos a ideia de usar o Confluence como uma ferramenta que resolveria simultaneamente três problemas:
- Criando uma base de conhecimento.
- Desenvolvimento, armazenamento e atualização de documentação desenvolvida de acordo com o GOST.
- Armazenamento e atualização da documentação desenvolvida de acordo com o GOST.
Potencial confluência
Nossas expectativas em relação à funcionalidade Confluence não foram totalmente atendidas, mas após a conclusão do teste, uma atitude geralmente positiva em relação a essa ferramenta se formou. Abaixo, formulamos suas principais vantagens para o nosso departamento:
- Personalize e suporte a ferramenta por conta própria.
- Fácil de aprender.
- A capacidade de organizar uma base de conhecimento sobre os produtos da empresa e armazenar toda a documentação compilada em DOCX e PDF em um só lugar.
- Suporte para documentos com versão.
- Capacidade de usar tecnologia de fonte única.
- A possibilidade de trabalho conjunto de desenvolvedores e escritores técnicos em documentos.
- Armazenamento de documentos e informações de trabalho em um só lugar.
- A capacidade de desenvolver documentos a qualquer momento e de qualquer lugar do mundo.
Implementação
Para implementar o Confluence, selecionamos dois especialistas do departamento de redatores técnicos que estudaram e testaram os recursos da ferramenta.
Para suporte técnico contínuo, o departamento de administradores de sistemas nos designou um especialista. Ele respondeu rapidamente a problemas técnicos e ajudou a entender as configurações básicas da nova ferramenta.
Ao mesmo tempo, criamos um grupo de trabalho no departamento de redatores técnicos, cuja tarefa era planejar a estrutura de armazenamento de dados. Toda a estrutura do nosso servidor foi dividida em categorias correspondentes aos tipos de projetos da empresa. As categorias, por sua vez, foram divididas em espaços por produtos da empresa. Também identificamos uma categoria separada para a base de conhecimento interna.
Quando os responsáveis por testar os sistemas estudaram profundamente o trabalho no Confluence, começou o estágio do treinamento ponto a ponto. Demorou cerca de um mês para transferir conhecimento para todo o departamento.
Questões técnicas
A implementação do Confluence como um todo correu bem, mas houve problemas.
Layout e pré-impressão de documentos
“Eu costumava fazer isso no MS Word em alguns segundos. Como fazer o mesmo no Confluence? ” - fizemos a nós mesmos essa pergunta todos os dias durante todo o período de teste.
Portanto, não era óbvio como alinhar o conteúdo da tabela verticalmente ou atribuir um tamanho de ícone menor que 16 px.
De fato, o conjunto básico de funções de formatação de página no editor Confluence WYSIWYG é muito pior que o MS Word, mas a funcionalidade pode ser significativamente expandida se você entrar no modo de edição de código-fonte e trabalhar diretamente com o código HTML.
Lemos artigos, assistimos a vídeos de treinamento em layout HTML e compartilhamos as soluções que encontramos. Criamos uma página separada no Confluence, onde colocamos informações úteis sobre como trabalhar com essa ferramenta.
Atualização de Confluência e Plug-in
Após a primeira atualização do plug-in principal Scroll PDF Exporter, 80% das macros foram perdidas e a estrutura da página foi para Confluence. Mais tarde, aconteceu o que aconteceu por causa da nova funcionalidade do plugin. Em todo o departamento, restauramos a estrutura dos documentos por vários dias. Depois disso, fizemos um plano de atualização para o futuro, ao qual ainda aderimos:
- Execute a atualização na sexta-feira, quando a camada principal de trabalho da semana estiver concluída, a fim de eliminar possíveis problemas no fim de semana.
- Distribua a todos os usuários do sistema para informá-los da hora da atualização planejada.
- Antes de atualizar, faça backup do servidor.
- Atualize a versão do Confluence.
- Teste o servidor, verifique se todas as informações estão no lugar, se há links para recursos externos e internos.
- Se você precisar atualizar os plug-ins, faça backup do servidor novamente.
- Atualize seus plugins, um plug-in de cada vez.
- Teste o plug-in imediatamente após a atualização.
Notificações em massa
Quando a turbulenta atividade de escritores e desenvolvedores técnicos finalmente começou a ferver no Confluence, o administrador recebeu chamadas dos usuários do serviço. Eles pediram para salvá-los de um ataque em massa por notificações por email sobre as ações de outros usuários.
Por padrão, o usuário só precisava acessar uma página uma vez, após a qual era automaticamente adicionado pelo sistema à lista de observadores e recebia notificações sempre que essa página era alterada.
Além disso, o Confluence gentilmente fazia boletins semanais para usuários que listam as páginas mais populares do Confluence. Felizmente, esse problema já foi amplamente abordado na Internet. A solução é desativar as notificações correspondentes nas configurações do sistema:
Agora, os usuários receberão notificações apenas se seu nome for mencionado nos comentários no artigo.
Estabilidade do servidor
Para testar o Confluence, implantamos um servidor Windows. Nos estágios iniciais, o servidor geralmente "travava". Parte do problema acabou sendo RAM insuficiente no servidor (o tamanho recomendado é de 11 a 12 GB). Os problemas restantes desapareceram quando ativamos as configurações do sistema recomendadas nesses casos.
Agora o servidor está funcionando de maneira estável - as interrupções ocorrem cerca de uma vez em dois meses. No caso de uma falha, uma reinicialização é suficiente para repará-la.
Gerenciamento de documentos em Confluence
Hoje, na Confluence, escritores técnicos, programadores, engenheiros eletrônicos, o controle de qualidade trabalham juntos.
Planejamos abandonar completamente o MS Word, desenvolver documentos exclusivamente no Confluence e convertê-los em DOCX e PDF. Na realidade, descobriu-se que você pode ficar sem o longo processo de transferir toda a documentação existente para um novo formato e, em seguida, configurar modelos no Scroll PDF / Word Exporter. De acordo com nossas estimativas, levaria cerca de seis meses para fazer isso. Acabou sendo muito mais fácil transferir todos os documentos desenvolvidos no formato MS Word para o Confluence e mantê-los lá.
Decidimos não esperar uma formatação maravilhosa do Confluence de acordo com todos os requisitos do ESKD e simplesmente dividimos todos os documentos do usuário condicionalmente em documentos para o "cliente do estado" e documentos para "não o cliente do estado".
A primeira que criamos no formato DOCX, armazenamos e atualizamos no Confluence. Desenvolvemos o último diretamente no Confluence, exportando para PDF, se necessário.
Graças às macros internas, usamos a tecnologia de fonte única na documentação do usuário - agora não precisamos alterar manualmente um parâmetro em várias versões de documentos.
O conveniente editor WYSIWYG facilita as alterações no documento finalizado - capturas de tela, ícones e elementos gráficos permanecem no lugar.
O recurso de edição colaborativa permite que você colabore em um documento. Você pode compartilhar o documento com um especialista técnico diretamente no Confluence e discutir seus comentários em tempo real, em vez de espalhá-lo infinitamente pelo correio.
Para trabalhar fora do escritório, você não precisa configurar o acesso remoto. Para poder trabalhar em casa, você só precisa da Internet.
O Confluence oferece ao usuário a interface familiar da página da web, com a capacidade de configurar links cruzados e abrir várias guias no navegador para trabalhar de uma só vez.
Agora, armazenamos todos os documentos, elementos gráficos, fotos de dispositivos e também mantemos uma base de conhecimento sobre os produtos da empresa em um só lugar. Não há necessidade de pensar sobre onde pode estar a fonte das fotos ou a versão mais recente dos documentos.
O que mais você quer fazer
No momento, estamos configurando o processo de alinhamento da página do Confluence usando o plug-in Comala Workflow. No entanto, este plug-in não funciona com anexos do MS Word. Coordenamos esses documentos com a ajuda dos comentários da versão. Agora, estamos considerando opções para definir a aprovação automática de anexos DOCX. Gostaria que o processo de aprovação e aprovação fosse usado simultaneamente com as páginas do Confluence e os anexos no formato DOCX.
Quando configuramos a aprovação automática de anexos, tentaremos fazer uma conversão rápida do MS Word para PDF. E então - enviando documentos para o servidor do produto impresso, de onde a empresa de impressão leva os documentos para impressão.
Instruções de localização súbita
Nunca conseguimos abandonar o MS Word, mas, no processo de encontrar um substituto, de repente descobrimos algo mais. A Confluence reuniu desenvolvedores de diferentes departamentos, formou a base de conhecimento da empresa e se tornou o repositório de todos os documentos da empresa, independentemente de seu formato.
Nossa empresa tem um princípio: em qualquer situação incompreensível, tome decisões sistematicamente. Acreditamos que uma solução que se baseia em um modelo é melhor do que uma solução baseada em opinião ou intuição de um especialista.
No caso da Confluence, o modelo de Eric Rhys da The Lean Startup foi útil. No desenvolvimento de produtos, ajuda a girar, mudar a direção do desenvolvimento do produto. E na tarefa de encontrar um substituto para o MS Word, tente uma nova ferramenta de forma mais ampla e encontre benefícios relacionados.
Desejamos aos colegas escritores técnicos modelos úteis!