Procurando uma estrutura de práticas recomendadas para configurar um wiki para desenvolvedores?
Estarei gerenciando uma equipe que não teve o melhor histórico de documentação, comunicação e compartilhamento de conhecimento. Eu gostaria de ter uma estrutura configurada para facilitar o início da equipe nessa área.
Respostas:
Não se concentre muito em obter uma estrutura perfeita na frente, é melhor deixá-la crescer organicamente . É a cultura e o processo de comunicação que importam.
Abaixo estão algumas dicas para manter o wiki da equipe.
fundamentos
feedback de valor
Peça, colete e registre qualquer feedback que puder receber - e-mail, comentários na página wiki (btw mais conveniente), messenger, conversa.
gravação de feedback
{excerpt:hidden=true}information to be processed later{excerpt}
feedback de processamento
lidar com sugestões que impliquem trabalho a longo prazo
update DD.MM.YYYY: 475 pages of 1000 are processed
lidar com sugestões que parecem erradas para você
Nota lateral: nunca é demais pedir esclarecimentos ao remetente da sugestão. No entanto, é melhor você fazer sua parte do trabalho primeiro:
melhor rápido que perfeito
Confie na revisão e feedback. Se algo realmente precisar de correção, o tempo resolverá o problema para você
seja ousado
Seja ousado ao atualizar as páginas: corrija problemas , corrija a gramática, adicione fatos, verifique se as palavras estão corretas etc.
também explicado na Wikipedia
avançado
seja grato
As pessoas que dão feedback são um bem valioso, sejam gratas a elas. Essas pessoas dedicaram seu tempo e esforço não apenas para ler sua página, mas também para fornecer seus comentários. A grande maioria dos seus usuários não será tão generosa com você. Aqueles que compartilham seus pensamentos são "a nata" do seu público, sejam gratos por sua contribuição.
explicar TLA-s
Se você não consegue entender o que é o TLA? - você entendeu
registrar respostas para perguntas
Respeitar o tempo dos outros - registrar respostas
use pontos de interrogação
Em caso de dúvida, use pontos de interrogação
(?)
Exemplo:<this info> needs checking
links são seus amigos
matéria visual
relaxe e divirta-se
Lembre-se de que normalmente os leitores da sua página não precisam ser muito sérios.
podridão do link de luta
Tudo bem, pense nos caras que mantêm links em algum lugar em seus favoritos, arquivos de e-mail, documentos, etc.
<this page> has been moved to <that page>
<this document> has been removed because of <the reason>
Referências para leitura adicional
fonte
Primeiro, é importante escolher uma boa Wiki. Escolha um que:
A maior coisa que um Wiki de equipe de desenvolvimento precisa é de um "jardineiro": alguém responsável por determinar o layout e a estrutura dos documentos no Wiki. Não precisa ser um papel de período integral, mas o jardineiro deve ter um inglês forte e uma aptidão para explicar bem as coisas. O jardineiro deve criar modelos padrão para páginas, convenções de nomenclatura e determinar quais espaços para nome são necessários.
O jardineiro não é responsável por criar o conteúdo, reforçando mais sua estrutura. Por exemplo, se alguém fizer uma alteração em um produto, o jardineiro não será responsável por fazer a alteração no Wiki. No entanto, o jardineiro é responsável por garantir que a alteração seja feita e que seja feita de acordo com as diretrizes (e não apenas colada em uma página separada e não vinculada, por exemplo). O jardineiro pode revisar as alterações ou delegá-las a outra pessoa.
É importante estruturar o Wiki para atender às necessidades do público em vez das necessidades daqueles que criam conteúdo. Por exemplo, se você tiver uma interface do usuário ou equipe de segurança ou localização dedicada ao desenvolvimento de software, não coloque suas informações em seções separadas. Coloque-os na mesma seção que os desenvolvedores estão olhando. Ter tudo junto facilita muito a localização, garante que as coisas não sejam perdidas e identifica o conteúdo desatualizado mais rapidamente.
Um Wiki precisa de uma mudança de mentalidade. Muitas empresas estão acostumadas a informações que lhes são impostas. Um Wiki permite que os consumidores da informação a modifiquem. Isso deve ser fortemente incentivado (e recompensado, se necessário). Se a imprecisão for uma preocupação, peça aos revisores que configurem o Wiki para enviá-los por e-mail quando forem feitas modificações.
Um Wiki de desenvolvimento precisa de uma estratégia para lidar com o controle de versão. Se você possui um conjunto de documentos para a versão 1.0, o que acontece quando a versão 2.0 é lançada? Alguns dos documentos da versão 1.0 ainda podem se aplicar à 2.0, mas alguns podem ser substituídos. E se uma alteração for feita em um documento 1.0 após o lançamento do 2.0?
Um Wiki precisa de alguma maneira de medir o sucesso. Quantas pessoas estão usando? Eles encontraram o que estavam procurando? Você não precisa necessariamente de uma caixa grande e feia de classificação e comentário na parte inferior da página, mas um simples link "Enviar um e-mail a um ser humano sobre esta página" pode ser útil.
Por fim, os padrões de uso de um Wiki mudarão com o tempo. Lembre-se de revisar quaisquer padrões periodicamente para garantir que eles ainda estejam atendendo às necessidades do Wiki.
fonte
Embora seja uma boa idéia que todas as páginas wiki do projeto sigam um tema semelhante para que todos saibam onde encontrar as coisas, isso realmente não resolverá o problema de os desenvolvedores não atualizarem as páginas.
Você precisa encontrar uma maneira de fazer com que seus desenvolvedores vejam benefícios suficientes ao fazer essas coisas que eles conduzem e desejam. Caso contrário, eles simplesmente o verão como outro fardo burocrático de cima para baixo, sem o qual eles poderiam passar.
Eu já estive nessa situação, tanto onde o wiki era uma bagunça completa quanto altamente organizado e formal. O estado do wiki não afetou o nível de interesse dos desenvolvedores.
fonte