Dicas para criar documentação técnica eficaz para seu app da Shopify

Poucos desenvolvedores realmente gostam de escrever documentação técnica - eles preferem estar codificando! Mas às vezes a documentação é uma parte necessária do que você entrega. Essas dicas ajudarão você a criar conteúdo eficaz para dar suporte ao seu aplicativo da Shopify voltado para o comerciante.

Antes de nos aprofundarmos, porém, vamos esclarecer o que queremos dizer com documentação. Aqui, veremos alguns conceitos de alto nível sobre a criação de artigos ou tópicos para acompanhar seu aplicativo: conteúdo adicional que ajuda os comerciantes a começar a usar seu aplicativo, pode ensiná-los a usá-lo e ajudá-los se eles se depararem com qualquer problema. Geralmente é chamado de help ou docs .

Embora esse tipo de documentação seja separado de seu aplicativo, é melhor considerá-lo parte integrante de sua oferta geral — em outras palavras, trate-o com o mesmo cuidado e respeito que você usa para projetar e codificar o próprio aplicativo. Sua documentação técnica também funciona como uma ferramenta de marketing: mostra seu profissionalismo, reflete a qualidade de seu aplicativo e pode aumentar a adoção de seu aplicativo.

1. Minimize a necessidade de documentação com um UX sólido

Um aplicativo bem projetado terá uma ótima experiência do usuário, e muitos de seus recursos serão fáceis de descobrir apenas olhando para ele. Isso é bom! Quanto menos documentação você tiver para escrever, melhor. E quanto menos documentos um comerciante precisar ler, melhor para ele.

As palavras no próprio aplicativo, que geralmente são chamadas de texto da interface do usuário, são críticas - essas são as palavras que os comerciantes que usam seu aplicativo verão e que os guiarão sempre que o usarem.

Este texto de interface do usuário é um tipo de documentação em si. Um aplicativo normalmente possui campos onde um comerciante pode inserir dados, botões para clicar e assim por diante. Certifique-se de que todos esses elementos da interface do usuário tenham rótulos úteis para que fique claro para que serve um campo.

Se os rótulos não forem suficientes para transmitir exatamente o que precisa ser feito em uma determinada parte do seu aplicativo, você pode incluir pequenas linhas de texto em seu aplicativo para explicar o que fazer em uma tela ou área específica. O app Shop, por exemplo, usa explicações curtas para as seguintes configurações:

Não entraremos em mais detalhes sobre esse tipo de documentação, mas confira as diretrizes do Shopify Polaris para obter ótimas informações sobre como criar o conteúdo de interface do usuário mais eficaz para seu aplicativo.

Em geral, porém, quanto melhor seu aplicativo estiver documentado na própria interface do usuário, mais fácil será para os comerciantes usá-lo e você terá menos necessidade de acompanhar a documentação técnica.

Você também pode gostar de: UX Writing: 10 dicas para criar conteúdo eficaz.

2. Sempre tenha em mente o usuário de seus aplicativos — lojistas da Shopify

Assim como você projeta seus aplicativos para comerciantes, crie sua documentação para comerciantes também.

“Assim como você projeta seus aplicativos para comerciantes, crie sua documentação para comerciantes também.”

Por exemplo, seu aplicativo provavelmente foi projetado com certas expectativas sobre o que o usuário já sabe, seja sobre estoque, marketing, remessa ou algum outro aspecto da administração de uma empresa. Seus documentos devem usar a mesma linguagem com a qual os comerciantes estão familiarizados em seu trabalho diário.

Isso pode ser melhor demonstrado com um exemplo de cabeçalho de tópico. Imagine que você criou um aplicativo que ajuda em um aspecto específico de lidar com devoluções e trocas online. Agora imagine o comerciante encontrando este título para um tópico em seus documentos:

Certificação de produtos reapresentados ao local de venda

Huh? Isso quase soa como uma tradução muito ruim. E se fosse isso em vez disso:

Autorização de devolução de produtos

Isso faz muito mais sentido! O cabeçalho revisado usa uma linguagem que os comerciantes entendem e provavelmente usam diariamente. Alguém que dê uma olhada em sua documentação saberá imediatamente o que este tópico cobre.

Certifique-se de que as palavras que você está usando em seus documentos sejam comuns e significativas para os comerciantes.

“Certifique-se de que as palavras que você está usando em seus documentos sejam comuns e significativas para os comerciantes.”

O mesmo vale para o jargão técnico. Como desenvolvedor, você provavelmente está bastante familiarizado com termos como APIs, métodos e logs de erros, por exemplo. Mas muitos comerciantes não sabem o que esses termos significam ou como eles são relevantes para usar seu aplicativo, então evite-os em seu conteúdo.

Um bom exemplo de documentação que usa a linguagem dos lojistas é o conteúdo do Launchpad na Central de ajuda da Shopify. Sua primeira linha explica o que este aplicativo Shopify Plus faz e as atividades comerciais específicas para as quais ele foi projetado:

Este conselho de manter seu público em mente pode parecer simples e óbvio, mas na verdade é muito fácil cair na armadilha de escrever o que você sabe, em vez do que seu público precisa saber. Voltaremos a tocar nisso mais tarde.

3. Comece a escrever seus documentos assim que começar a codificar

Algumas pessoas pensam que escrever a documentação começa depois que a codificação é concluída. Afinal, como você pode explicar como usar um aplicativo se ele ainda não foi construído, certo?

Não! Na verdade, é muito importante começar a escrever muito antes disso. A documentação resulta melhor quando é tratada como código: prototipar, descartar conforme necessário, iterar e melhorar.

A primeira passagem de seus documentos estará longe de ser perfeita, e tudo bem. O importante é começar a escrever suas ideias para que você possa reescrever, editar e reescrever um pouco mais, de novo e de novo - assim como você trabalha para fazer seu código atingir seus objetivos e rodar sem erros.

“A primeira passagem de seus documentos estará longe de ser perfeita, e tudo bem. O importante é começar a anotar suas ideias para que você possa reescrever, editar e reescrever um pouco mais, de novo e de novo - assim como você trabalha para fazer seu código atingir seus objetivos e rodar sem erros.

Se você tiver os recursos, geralmente é uma boa ideia contratar alguém que não ajudou a desenvolver o aplicativo para escrever os documentos. Por exemplo, um redator técnico profissional ou designer de conteúdo pode criar e escrever o conteúdo para você. Mas mesmo se você contratar alguém para escrever, envolva-o com seu projeto o mais cedo possível para que tenha contexto suficiente. Para obter mais informações sobre isso, você pode conferir meu artigo no Medium, Seu redator técnico é um enfeite ou um ingrediente principal?

Você também pode gostar de: 10 mitos sobre prototipagem, descobertos.

4. Crie documentação baseada em tarefas

Parafraseando um velho ditado, você pode criar dois tipos diferentes de documentação para algo: como funciona e como funciona.

Como funciona a documentação tende a ser mais técnica e geralmente é mais como material de referência para os técnicos inclinados. Às vezes, isso também é chamado de conteúdo centrado em recursos.

Mas o que você deve criar para o seu app é um conteúdo que explique como funciona . Em outras palavras, forneça instruções que mostrem aos comerciantes como usar seu aplicativo para atingir seus objetivos finais. Isso geralmente é chamado de documentação baseada em tarefas.

“Forneça instruções que mostrarão aos comerciantes como usar seu aplicativo para atingir seus objetivos finais.”

Depois que um lojista adiciona seu app à loja da Shopify, ele quer que ele resolva um problema para ele. Mas, dependendo do que seu aplicativo faz, eles podem primeiro ter que fazer alguma configuração do aplicativo, transferir alguns dados para ele ou configurá-lo de outra forma para que ele possa começar a funcionar.

Essas são as primeiras tarefas nas quais você pode se concentrar em escrever: configurar e configurar o aplicativo para suas necessidades específicas.

Em seguida, você pode passar para as próximas tarefas que eles precisarão fazer para usar o aplicativo.

Para lhe dar uma ideia melhor do que são os dois tipos de conteúdo contrastantes, aqui está um exemplo. Os documentos centrados em recursos podem ter um tópico chamado “Estrutura de arquivo CSV” que descreve as colunas que estão em um arquivo de valores separados por vírgula e os tipos de dados para cada coluna, e um tópico chamado “Exportações CSV” que descreve como os dados em esse arquivo pode ser usado por outro sistema.

Por outro lado, os documentos baseados em tarefas podem ter tópicos com títulos como estes:

• Adicione seus produtos ao arquivo CSV
• Verifique os produtos no arquivo CSV
• Exporte seu inventário para outro sistema

Observe como aqui, mesmo sozinhos, os títulos transmitem em linguagem útil as tarefas que o comerciante pode querer fazer. Eles também usam palavras e termos orientados a tarefas com os quais um comerciante provavelmente está familiarizado.

Os comerciantes geralmente ficarão mais felizes com documentos baseados em tarefas. A maior parte da Central de ajuda da Shopify usa conteúdo baseado em tarefas, como mostra este exemplo de tópicos para o app Kit:

Você também pode gostar de: 5 estratégias principais para melhorar o suporte do seu aplicativo.

5. Faça com que seus documentos sejam revisados ​​e testados por outra pessoa

Sua documentação precisa ser revisada e testada com tanto cuidado quanto o próprio app. E é importante que você faça com que as pessoas que não estão muito familiarizadas com seu aplicativo façam algumas dessas revisões. Não confie apenas em você!

Um grande benefício de ter alguém revisando seus documentos é que eles não são especialistas em seu aplicativo. Por ser um pouco afastado do processo de desenvolvimento, um revisor independente não terá todo o conhecimento que você tem e, portanto, não fará suposições que você possa fazer. Isso às vezes é chamado de “maldição do conhecimento”. Para saber mais sobre esse conceito, consulte a Wikipedia ou o livro de Steven Pinker , The Sense of Style .

Em resumo, porém, se você deixar a revisão para si mesmo, poderá ser sutilmente influenciado por sua experiência com o aplicativo e pelo conteúdo que escreveu. Por outro lado, se alguém entrar com novos olhos, terá uma chance maior de perceber se uma abordagem mais orientada para a tarefa é necessária, lacunas onde a documentação adicional pode ser útil, informações desatualizadas e até mesmo o estranho erro de digitação que você pode não ver.

Sua documentação sempre se beneficiará de uma revisão feita por alguém além dos desenvolvedores.

Ótima documentação significa usuários satisfeitos

Criar documentação para um aplicativo pode não ser a coisa mais importante ou favorita em sua lista de tarefas, mas realmente vale a pena o esforço para criar ótimos documentos que ajudarão os comerciantes a usar seu aplicativo com eficiência.

As dicas neste artigo apenas abordam superficialmente tudo o que está envolvido na criação de documentação técnica. Se você quiser se aprofundar, aqui estão alguns recursos adicionais para explorar:

• Write the Docs é uma organização que possui uma riqueza de informações em seu site, incluindo um Guia de documentação.
• O Google oferece alguns cursos introdutórios de redação técnica em https://developers.google.com/tech-writing.
• Escrita Estratégica para UX por Torrey Podmajersky se concentra no conteúdo da interface do usuário, mas cobre muito em um livro fino.
• A Bold Commerce cria vários apps da Shopify com conteúdo complementar. Confira sua abordagem à documentação.

Independentemente de como você criar seus documentos, lembre-se de se concentrar nos objetivos de seus comerciantes, mantenha a linguagem simples e direta e certifique-se de que outra pessoa revise sua documentação técnica antes de publicá-la.