Estrutura dos guias

Nossos guias independentes são estruturados de acordo com as seguintes seções:

Introdução que segue um padrão específico. Serve para apresentar o produto/plataforma. É o único arquivo que não é feito em Markdown.

Breve descrição da ferramenta ou plugin a ser documentado. É uma boa prática enumerar e vincular os passos de integração aqui, indicando quando um ou mais são opcionais e no entanto recomendados.

Lista de coisas que devem estar prontas para começar a integração. Geralmente, são apresentados em forma de tabela, contendo 3 colunas (requisito, descrição e especificações).

Esta seção da documentação geralmente abrange mais de uma entrada de menu e apresenta os passos que devem ser seguidos, do início ao fim, para realizar uma integração. É uma boa prática usar descrições claras para cada título de passo.

Se houver um fluxo de teste, ele deve ser incluído aqui. Se esse elemento estiver incluso, você também deve criar uma entrada de menu que explique como subir para produção depois que o fluxo de teste for concluído.

Se houver problemas comuns que os desenvolvedores possam encontrar e que as partes interessadas tenham identificado, é uma boa prática incluí-los aqui. Separe isso do fluxo de integração no menu com uma linha, e certifique-se de incluir apenas a solução de problemas para a integração (não para o produto com o qual está sendo integrado).

A maioria das documentações não requer esta seção, mas as partes interessadas podem solicitá-la. Se esse for o caso, certifique-se de que as perguntas frequentes contenham apenas informações que não possam ser incluídas em nenhuma outra seção da documentação. Caso contrário, simplesmente inclua essas informações na seção correspondente. Elas devem ser separadas do fluxo normal de integração.

É possível solicitar a inclusão de outras informações que, embora sejam importantes, não fazem parte do fluxo de integração. Você pode adicionar essas informações, mas mantenha-as separadas do fluxo de integração com uma linha para evitar confundir seus leitores. O termo "conteúdo adicional" é usado aqui como um exemplo. Você deve pensar em um nome apropriado para cada seção que adicionar como outra informação.