A documentación do software é só un conxunto de artigos. Pero mesmo eles poden volverte tolo. En primeiro lugar, pasas moito tempo buscando as instrucións necesarias. Entón entendes o texto escuro. Fai o que está escrito, pero o problema non está resolto. Buscas outro artigo, póñase nervioso... Unha hora despois renuncias a todo e marchas. Así funciona a mala documentación. O que o fai así e como solucionalo - le debaixo do corte.
Había moitas deficiencias na nosa antiga documentación. Levamos case un ano reelaborando para que o escenario descrito anteriormente non afecte aos nosos clientes. Mirar, и .
Problema 1: artigos pouco claros e mal escritos
Se a documentación é imposible de entender, para que serve? Pero ninguén escribe artigos incomprensibles a propósito. Ocorren cando o autor non pensa no público e no propósito, bota auga e non revisa o texto para detectar erros.
- Audiencia. Antes de escribir un artigo, cómpre pensar no nivel de preparación do lector. É lóxico que nun artigo para un principiante non se salte os pasos básicos e deixes termos técnicos sen explicación, pero nun artigo sobre unha característica rara que só precisan os profesionais, debes explicar o significado da palabra PHP.
- Meta. Unha cousa máis para pensar con antelación. O autor debe establecer un obxectivo claro, determinar o efecto útil do artigo e decidir que fará o lector despois de lelo. Se non se fai isto, acabará coa descrición por mor da descrición.
- Auga e bichos. Hai moita información innecesaria e burocracia, os erros e os erros tipográficos interfiren coa percepción. Aínda que o lector non sexa un nazi de gramática, o descoido no texto pode desactivalo.
Considere os consellos anteriores e os artigos serán máis claros, garantidos. Para facelo aínda mellor, usa o noso .
Problema 2. Os artigos non responden a todas as preguntas
É malo cando a documentación non segue o desenvolvemento, non responde a preguntas reais e os erros nela non se corrixen durante anos. Son problemas non tanto do autor, senón da organización dos procesos dentro da empresa.
A documentación non segue o desenvolvemento
A función xa está en versión, o marketing planea cubrila e despois resulta que o novo artigo ou tradución aínda non está na documentación. Incluso tivemos que aprazar o lanzamento por iso. Podes pedirlle a todos que entreguen as tarefas aos escritores técnicos a tempo tanto como queiras, pero non funcionará. Se o proceso non está automatizado, a situación repetirase.
Fixemos cambios en YouTrack. A tarefa de escribir un artigo sobre unha nova función recae no escritor técnico no mesmo momento en que a función comeza a ser probada. Entón o marketing aprende sobre iso para prepararse para a promoción. As notificacións tamén chegan ao mensaxeiro corporativo de Mattermost, polo que é simplemente imposible perderse noticias dos desenvolvedores.
A documentación non reflicte as solicitudes dos usuarios
Estamos afeitos a traballar así: saíu unha función, falamos diso. Describimos como acendelo, apagalo e facer axustes finos. Pero e se un cliente usa o noso software dun xeito que non esperabamos? Ou ten erros nos que non pensamos?
Para garantir que a documentación sexa o máis completa posible, recomendamos analizar as solicitudes de soporte, as preguntas en foros temáticos e as consultas nos buscadores. Os temas máis populares trasladaranse aos escritores técnicos para que poidan complementar os artigos existentes ou escribir outros novos.
Non se mellora a documentación
É difícil facelo perfectamente de inmediato; aínda haberá erros. Podes esperar comentarios dos clientes, pero é improbable que informen de todos os erros tipográficos, inexactitudes, artigos incomprensibles ou non atopados. Ademais dos clientes, os empregados len a documentación, o que significa que ven os mesmos erros. Isto pódese usar! Só tes que crear condicións nas que sexa fácil informar dun problema.
Temos un grupo no portal interno onde os empregados deixan comentarios, suxestións e ideas sobre documentación. O soporte necesita un artigo, pero non existe? O probador notou a imprecisión? Queixouse o socio aos responsables de desenvolvemento dos erros? Todos neste grupo! Os escritores técnicos arranxan algunhas cousas de inmediato, transfiren algunhas cousas a YouTrack e danlle tempo a outras para pensar. Para evitar que o tema morre, de cando en vez recordámosvos a existencia do grupo e a importancia do feedback.
Problema 3. Leva moito tempo atopar o artigo axeitado.
Un artigo que non se pode atopar non é mellor que un artigo que non se pode atopar. O lema dunha boa documentación debe ser "Fácil de buscar, fácil de atopar". Como conseguir isto?
Organiza a estrutura e determina o principio de elección dos temas. A estrutura debe ser o máis transparente posible para que o lector non pense: "Onde podo atopar este artigo?" En resumo, hai dous enfoques: desde a interface e desde as tarefas.
- Desde a interface. O contido duplica as seccións do paneis. Este era o caso da antiga documentación do sistema ISP.
- De tarefas. Os títulos dos artigos e seccións reflicten as tarefas dos usuarios; Os títulos case sempre conteñen verbos e respostas á pregunta "como facer". Agora pasamos a este formato.
Sexa cal sexa o enfoque que elixas, asegúrate de que o tema sexa relevante para o que buscan os usuarios e que estea cuberto de forma que responda especificamente á pregunta do usuario.
Configurar unha busca centralizada. Nun mundo ideal, a busca debería funcionar aínda que non faltes de ortografía ou cometas un erro coa lingua. A nosa busca en Confluence ata agora non nos pode agradar con isto. Se tes moitos produtos e a documentación é xeral, adapta a busca á páxina na que se atopa o usuario. No noso caso, a busca na páxina principal funciona para todos os produtos e, se xa estás nunha sección específica, só para os artigos nela.
Engade contido e migas de pan. É bo cando cada páxina ten un menú e rutas de navegación: o camiño do usuario á páxina actual coa posibilidade de volver a calquera nivel. Na antiga documentación do sistema ISP, tiñas que saír do artigo para acceder ao contido. Era un inconveniente, así que o arranxamos no novo.
Coloca ligazóns no produto. Se as persoas veñen apoiar unha e outra vez coa mesma pregunta, ten sentido engadir unha pista coa súa solución á interface. Se tes datos ou información sobre cando un usuario está experimentando un problema, tamén podes notificalo cunha lista de correo. Móstralles preocupación e quita a carga do apoio.
Á dereita na ventá emerxente hai unha ligazón a un artigo sobre a configuración de DNSSEC na sección de xestión de dominios de ISPmanager
Establecer referencias cruzadas dentro da documentación. Os artigos que estean relacionados entre si deben estar "ligados". Se os artigos son secuenciais, asegúrate de engadir frechas cara adiante e cara atrás ao final de cada texto.
O máis probable é que unha persoa busque unha resposta á súa pregunta non para ti, senón para un motor de busca. É unha mágoa se non hai ligazóns á documentación alí por razóns técnicas. Entón, coida a optimización dos motores de busca.
Problema 4. O deseño desactualizado interfire coa percepción
Ademais dos textos malos, a documentación pode estropearse polo deseño. A xente está afeita a ler materiais ben escritos. Blogs, redes sociais, medios: todo o contido preséntase non só bonito, senón tamén fácil de ler e agradable á vista. Polo tanto, pode comprender facilmente a dor dunha persoa que ve texto como na captura de pantalla que aparece a continuación.
Neste artigo hai tantas capturas de pantalla e aspectos destacados que non axudan, senón que só interfiren coa percepción (pódese facer clic na imaxe)
Non deberías facer unha lectura longa da documentación cunha chea de efectos, pero cómpre ter en conta as regras básicas.
Maquetación. Determine o ancho do texto do corpo, a fonte, o tamaño, os títulos e o recheo. Contrata un deseñador e, para aceptar o traballo ou facelo ti mesmo, le o libro "Tipografía e deseño" de Artyom Gorbunov. Presenta só unha vista do deseño, pero é bastante suficiente.
Dotacións. Determina o que require énfase no texto. Normalmente, este é un camiño na interface, botóns, insercións de código, ficheiros de configuración, bloques "Ten en conta". Determinar cales serán as asignacións destes elementos e rexistralas regulamentariamente. Teña en conta que canto menos descarga, mellor. Cando hai moitos, o texto é ruidoso. Mesmo as comiñas crean ruído se se usan con demasiada frecuencia.
Imaxes. Acorda co equipo en que casos son necesarias capturas de pantalla. Definitivamente non hai necesidade de ilustrar cada paso. Un gran número de capturas de pantalla, incl. botóns separados, interferir coa percepción, estragar o deseño. Determina o tamaño, así como o formato dos destacados e das sinaturas nas capturas de pantalla, e rexistraos na normativa. Lembra que as ilustracións deben corresponderse sempre co que está escrito e ser relevantes. De novo, se o produto se actualiza regularmente, será difícil facer un seguimento de todos.
Lonxitude do texto. Evita artigos demasiado longos. Divídeos en partes e, se isto non é posible, engade contido con ligazóns de ancoraxe ao comezo do artigo. Unha forma sinxela de facer un artigo visualmente máis curto é ocultar os detalles técnicos necesarios para un círculo estreito de lectores baixo un spoiler.
Форматы. Combina varios formatos nos teus artigos: texto, vídeo e imaxes. Isto mellorará a percepción.
Non intentes tapar os problemas cun deseño fermoso. Sinceramente, nós mesmos esperabamos que o "envoltorio" gardase a documentación obsoleta - non funcionou. Os textos contiñan tanto ruído visual e detalles innecesarios que a normativa e o novo deseño eran impotentes.
Gran parte do anterior estará determinado pola plataforma que utilices para a documentación. Por exemplo, temos Confluence. Eu tamén tiven que xogar con el. Se che interesa, le a historia do noso desenvolvedor web: .
Por onde comezar a mellorar e como sobrevivir
Se a súa documentación é tan ampla como a do ISPsystem e non sabe por onde comezar, comeza cos maiores problemas. Os clientes non entenden o documento: mellorar os textos, facer regulamentos, formar escritores. A documentación está desactualizada: coida dos procesos internos. Comeza cos artigos máis populares sobre os produtos máis populares: pide asistencia, consulta as análises do sitio e consultas nos buscadores.
Digamos de inmediato: non será fácil. E tampouco é probable que funcione rapidamente. A menos que estea comezando e faga o correcto de inmediato. Unha cousa que sabemos con certeza é que mellorará co paso do tempo. Pero o proceso nunca rematará :-).
Fonte: www.habr.com