Abaixo algumas dicas para criar uma boa documentação independente do tipo que você estiver criando, portanto são dicas complementares, lembre-se de como premissa seguir o template do confluence desse tipo, caso exista.
As dicas abaixo basicamente dizem pra você criar docs pensando num modelo de Wiki, assim como a Wikipedia ou sites de wiki de jogos como Dota, Lol, Minecraft.
O porque é simples, essa é a forma que a comunidade entende como adequada para contribuir e aprender. As principais dicas são:
Explique no primeiro parágrafo de forma sucinta o que é a funcionalidade/termo, etc. As pessoas geralmente estão com pressa, cheias de afazeres e precisam da forma mais rápida saber de resumidamente o que é tal assunto, se ela precisar de mais contexto, continuará lendo, caso contrário as primeiras frases já podem resolver seu problema, exatamente como fiz aqui, entrego o "o que” o mais rápido possível e depois contextualizo se a pessoa quiser entender mais.
Nos outros parágrafos, ir dando mais detalhes com mais texto, divida por sessões, como: Exemplos, Contextualização, etc.
É importante ter títulos claros e divulgar o link da sua doc sempre a linkando em outras páginas, sempre que o assunto dela for citado. Nós fazemos documentações pensando no próximo que poderá aprender com ela, por isso é necessário fazer com que seja o mais fácil possível acha-la.
Pratique isso, sempre faça link nos termos e nomes que precisam de mais explicações, até crie novas páginas, mesmo que não tenham nenhum conteúdo no início, lá deixar um to do pra alguém ser motivado a contribuir no futuro e quando o fizer existirão várias páginas já apontando pra ela, com isso também é evitada a duplicidade de explicações que leva tempo pra fazer e fica facilmente desatualizada criando uma falta de credibilidade pra essa doc.
Complementando o “Não duplique, faça referência", quando você procurar por algo e encontrar mais de uma página explicando sobre, puxe a responsabilidade de conversar com os editores da página e tirar essa duplicidade.
No caso de uma página de um assunto x acabar explicando outro pra poder fazer a contextualização
Nomear a página dona do assunto (pode ser o caso de criar uma nova) e então fazer com que as outras façam o link pra ela ao invés de repetir a explicação.
No caso de um assunto x ter mais de uma página só pra explicar a mesma coisa
Decidir qual das duas será a principal, na outra fazer link pra principal e arquivá-la pra evitar que a informação se perca novamente.