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.

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

  • P: e se atualmente não tiver tempo para processar adequadamente as informações?
  • R: salve-o na página como está - para processamento futuro e oculte-o dos leitores regulares, como a seguir:{excerpt:hidden=true}information to be processed later{excerpt}

• feedback de processamento

  • tente fazê-lo o mais rápido possível. Detalhes e contexto que parecem óbvios para você ou remetente agora, podem ser esquecidos um dia, semana ou mês depois  
  • considere soluções alternativas para os problemas apontados no feedback. Exemplo:
    • (feedback) ei, a informação que eu preciso é misturada com uma inútil
    • (ação errada) OK, removo o que você não precisa
    • (ação correta) OK Vou dividir as informações para um de seu interesse e o restante que possa interessar a outra pessoa

lidar com sugestões que impliquem trabalho a longo prazo

• P: e se a sugestão for dizer "colete e reorganize todos os dados relevantes documentados em milhares de outras páginas"?
• R: adicione uma seção TODO-s à sua página (se ainda não estiver lá) e registre a sugestão nesta seção. Mais tarde, você pode usá-lo também para acompanhar seu progresso
  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:

• verifique o histórico da página, levando em consideração a data da revisão. Sempre há uma chance de o remetente apontar para o problema da versão anterior que já foi corrigida
• olhe mais de perto a página / seção mencionada e pergunte a si mesmo: o que poderia fazer com que ele pensasse assim?
• (depois de um pouco de treinamento com o truque acima), você descobrirá que na maioria, se não em todos os casos, existe uma área distinta para melhorias.
  • Imagine, por exemplo, o usuário reclamando da falta de informações que estão presentes em algum lugar da página. Apesar de parecer errado na superfície, essa reclamação geralmente indica um problema sério na página: a saber, que algumas informações importantes são difíceis de encontrar. Dar uma visibilidade que merece, melhorará a página.

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ê

• isso também se aplica à auto-revisão. Registre o rascunho do que você deseja colocar na página e revise-o uma hora (ou dia ou semana) depois - esse truque pode fazer maravilhas
• não perca tempo aperfeiçoando as coisas na primeira tentativa - é impossível
  • registre as informações assim que parecer pouco aceitável e peça aos interessados ​​que as revisem

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.

• Acima é baseado no princípio da Wikipedia e é melhor explicado, bem, na Wikipedia
  • ... mas tenha cuidado - cuide do bem comum e não edite de forma imprudente: um esclarecimento ao princípio acima,
    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

• use links para isso, se possível: TLA

registrar respostas para perguntas

Respeitar o tempo dos outros - registrar respostas

• Pode levar um segundo para responder à pergunta, mas pense no cara que fez a pergunta? (S) ele levou um tempo para ler sua página, para tentar encontrar a resposta, entrar em contato com você e aguardar sua resposta. Se você registrar a resposta na página, economizará todo esse tempo para o próximo sujeito que tiver essa pergunta.
• Registre as respostas para suas próprias perguntas. O que não está claro para você, pode não estar claro para o próximo leitor.

use pontos de interrogação

Em caso de dúvida, use pontos de interrogação

• Sintaxe de confluência como um exemplo: (?) Exemplo:<this info> needs checking
• dessa forma, qualquer leitor pode ver claramente que tipo de informação você precisa; as chances são altas de que alguém possa ajudá-lo a esclarecer as coisas

links são seus amigos

• DRY - não tente copiar informações quando você pode fornecer o link , em vez
• aprender a resumir quando necessário
  • algum link - ei, o que é isso?
  • algum link - Wikipedia, a enciclopédia livre que qualquer um pode editar.

matéria visual

• Quando tiver tempo, revise sua página perguntando a si mesmo se é fácil para o leitor entender o (s) argumento (s) que deseja
• Pode ser bastante difícil encontrar substância em um fluxo não estruturado de consciência

  ^{...Dei a ele todo o prazer que consegui levá-lo até que ele me pedisse para dizer sim, e eu não responderia primeiro, apenas olhava para o mar e o céu. Estava pensando em tantas coisas que ele não sabia de Mulvey, Stanhope, Hester e Hester. pai e velho capitão Groves e os marinheiros tocando todos os pássaros voam e eu digo: incline-se e lave a louça que eles chamaram no píer e na sentinela em frente à casa do governador com a coisa em volta do capacete branco, pobre diabo meio assado e as meninas espanholas rindo em seus xales, pentes altos e leilões de manhã, os gregos, os judeus, os árabes e o diabo sabem quem mais, de todos os confins da Europa e da rua Duke e do mercado de aves, todos rondando fora de Larby Sharons e dos pobres burros adormecer meio adormecido e os vagos companheiros nas mantas adormecem à sombra nos degraus eas grandes rodas das carroças dos touros e o velho castelo de milhares de anos, sim, e aqueles bonitos mouros, todos de branco e turbantes como reis, pedindo que você se sente em sua pequena loja e Ronda com as velhas vitrines das posadas 2 olhos esbugalhados, uma treliça escondia para que seu amante beijasse o ferro e as vinícolas entreabertas à noite e as castanholas e a noite em que perdemos o barco em Algeciras, o vigia sereno com sua lâmpada e com aquela terrível torrente no fundo O e o mar o mar vermelho às vezes gosta de fogo e o pôr do sol glorioso e as figueiras nos jardins da Alameda sim e todas as ruas esquisitas e pequenas e casas cor de rosa e azuis e amarelas e jardins de rosas e jessamine e gerânios e cactos e Gibraltar como uma garota onde eu estava uma flor da montanha sim quando eu coloco a rosa no meu cabelo como oAs meninas andaluzas usavam ou devo usar um sim vermelho e como ele me beijou sob o muro dos mouros e eu o pensava tão bem quanto o outro e então eu perguntei com meus olhos para perguntar novamente sim e então ele me perguntou se eu deveria dizer sim minha flor da montanha e primeiro eu coloquei meus braços em volta dele sim e o puxei para mim, para que ele pudesse sentir meus seios todo perfume sim e seu coração estava ficando louco e sim, eu disse que sim.}

relaxe e divirta-se

Lembre-se de que normalmente os leitores da sua página não precisam ser muito sérios.

• quando achar apropriado se divertir - faça-o

podridão do link de luta

• Você está disposto a mover alguma página ou recurso?
  Tudo bem, pense nos caras que mantêm links em algum lugar em seus favoritos, arquivos de e-mail, documentos, etc.
• Quando você (re) move a página ou um documento, mantenha um espaço reservado onde ele estava localizado anteriormente, para ajudar os visitantes a entender o que aconteceu com ele e para onde ir
  • <this page> has been moved to <that page>
  • <this document> has been removed because of <the reason>

Referências para leitura adicional

• Políticas e diretrizes da Wikipedia
• Guia de notação de confluência
• Padrões Wiki

Primeiro, é importante escolher uma boa Wiki. Escolha um que:

1. Está bem conservado e tem um bom suporte.
2. Oferece suporte à autenticação do usuário e possui controle de acesso em documentos ou espaços para nome.
3. Rastreia alterações nos documentos e fornece um histórico.
4. Permite notificação por email de alterações no documento.
5. Tem um bom editor, de preferência WYSIWYG, e suporta listas, tabelas e upload de imagens.

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.

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.