Artefatos em Wiki

Devido a enorme flexibilidade, as paginas Wiki podem rapidamente formarem um complicado emaranhado de informacoes. Assim, organizar de alguam forma seu conteudo é interessante.

As regras para a colocacao de artefatos (paginas) em wiki sao:

1. Utilize tags.
2. Tenha certeza que o item 1 foi contemplado.
3. Revise o item 2.
4. Tenha atencao no local (hierarquia) onde a pagina esta sendo criada.
5. Revise o item 4.
6. Evite acentuacao e/ou caracteres especiais nos nomes de paginas.
7. Para artefatos (paginas) que sao imutaveis, ou deveriam ser, por exemplo, atas de reunioes, release notes, registro de participacao, relatorios, etc, procure iniciar o nome do artefato com uma data, seguido de um espacao e um traco. Exemplo: 2008.03.05 - Merlin - Liberacao Alpha1
8. Todas as datas seguem o formato: AAAA.MM.DD, o que facilita a ordenacao em qualquer dispositivo.
9. Revise o item 8.
10. Para artefatos (paginas) de projetos de clientes, vide secao Página de Projetos, abaixo.
11. Todos os títulos e subtítulos (de quaisquer níveis), quando formados por palavras compostas, Devem Possuir as Iniciais em Maiúsculas, com excecao das preposicoes, adverbios e adjuntos, como "em, ou, a, de, para, com, do, de" e outros semelhantes.
12. Tenha cuidado com o nivel de permissao dado a pagina criada. Na duvida, procure informacoes junto a outras pessoas da equipe, com gerente ou com o administrador do sistema.
13. Revise as permissoes das paginas.
14. Revise o item 13, agora com atencao! - Lembre-se, seu login é armazenado no sistema, e o vazamento de informacoes é facilmente localizavel, sendo voce o responsavel.
15. Adicione comentarios uteis as edicoes realizadas nos artefatos (paginas, anexos, etc).
16. Revise o item 15.
17. Se for uma edicao de pequeno vulto, marque o item "Minor change" ao rodape da pagina, para evitar notificacoes para usuarios cadastrados no artefato.
18. Ao final, antes de salvar, revise o conteudo: nome do artefato, links quebrados, permissoes e comentarios.
19. Nao precisa revisar o item 18, senao voce vai perder muito tempo
20. Publique.

Páginas de projetos

Páginas de clientes 

Convenciona-se que os nomes das páginas dos clientes sigam a nomenclatura:

<sequencia> - <data> - <nome do cliente> - <cidade>, <uf> - Home

Onde:

sequencia: é um número sequencial a partir de 1, que indica o n-ésimo cliente conquistado.

data: é, como todas as datas no wiki da empresa, formatada com AAAA.MM.DD e indica a data de catalogação do cliente. Útil para fins históricos e estratégicos da empresa.

nome do cliente: é o nome do cliente reconhecido pela empresa e seus colaboradores.

cidade e uf: informam a localização do cliente 

Home: indica a página centralizadora dos projetos do cliente. 

 Exemplos:

1 - 2008.06.25 - Panazollo - Canoas, RS - Home

Subpáginas de clientes

Servem para centralizar diversos projetos em um cliente. Estão localizadas sempre como elementos-filho da página Home do cliente.

A nomenclatura dessas páginas é dada por:

<sequencia> - <data> - <nome do cliente> - <nome do projeto> - <cidade>, <uf> - Home

Onde:

sequencia, data, cidade, uf e Home: são análogos às páginas do cliente e, embora possam parecer informações redudantes, algumas vezes projetos do cliente podem existir em diversas localizações.

nome do projeto: deve ser identico ao utilizado no Jira.

As páginas de informacoes de cada projeto nao precisam seguir estruturas definidas, mas a premissa de colocar a data de criacao do documento (lembrando que esta regra vale para todas paginas wiki da empresa) deve ser mantida.

Na figura anexa,  uma ideia de como deve ser isso na pratica diaria.

Artefatos em Repositório Versionado

 Todos os artefatos armazenados em repositório versionado devem seguir um padrão de nomenclatura e de estruturação de diretórios. Essa padronização visa principalmente:

1. Permitir a fácil navegação entre os diferentes clientes, seus projetos, áreas de domínio, artefatos e seus tipos. Por exemplo, ter facilidade para encontrar todos os documentos do Cliente X, ou todos os documentos do cliente X que dizem respeito à área técnica, ou todos os documentos da área técnica que foram enviados pelo cliente para a empresa.
2. Permitir a localização unívoca de artefatos. Em suma, garantir que nenhum nome de artefato se repete em nenhum local da empresa e, da mesma forma, garantir uma identicação de recurso mesmo quando este seja retirado do repositório versionado. Para garantir essa qualidade, os artefatos são armazenados com um nome composto de diversos fragmentos, que correspondem à sua localização no repositório versionado. No decorrer desse capítulo, são mostrados exemplos dessa técnica.

Estrutura de diretórios

Os diretórios no repositório versionado seguem a estrutura abaixo:

 $dados............................................Diretorio do sistema operacional, a qual contem todos os dados da empresa.
  +-repositorios...................................Nome padrao "repositorios", que indica o local onde estao todos os repositorios versionados da empresa.
     +-$grupo......................................Tipo do repositorio, indica a finalidade do repositorio, como "public", "private" ou o nome de um cliente.
         +-$repositorio............................Repositorio versionado, um para cada projeto da empresa.
             +-trunk...............................Diretorio principal, com artefatos em desenvolvimento ou producao.
             +-branches............................Diretorio auxiliar, com artefatos em desenvolvimento que contem divergencias do diretorio principal.
             +-tags................................Diretorio imutavel com artefatos que correspondem a versoes de entrega ou versoes estaveis de recursos.

O  conteúdo dos diretórios abaixo de /trunk, /branches e /tags varia de projeto para projeto, e a estruturação deve ser acordada de antemão com a gerência do projeto, com concordância entre os perfis de arquitetos, analistas e projetistas. Diretórios iniciadios por $ (cifrão) são variáveis.

Uma possível estruturação de diretórios nesse caso é dada pela figura anexa (TODO).

Salienta-se que o uso de caracteres de acentuação, cedilhas, underscore e semelhantes devem ser evitados.

Nomes de artefatos versionados

Todos os artefatos versionados devem ser referenciados univocamente, independente de estarem ou não vinculados ao repositório. Isso garante, por exemplo, que ao receber um documento por email, este seja facilmente associado ao cliente, projeto e função (no projeto).

Para que isso seja possível, uma técnica de estruturação de nomes compostos é utilizada, conforme:

 $empresa - $cliente - $projeto - [$area]+ - [$data]? - $nomeDoArtefato

Nesse modelo, $ (cifrão) significa uma variável; valores entre \[\]\+ devem ocorrer pelo menos uma vez e; valores entre \[\]? são opcionais, podendo ocorrer zero ou uma vez. Datas, como sempre, são formatadas como _aaaa.mm.dd_.

Assim, é exemplo prático dessa nomenclatura:

3layer - targettrust - cursos - uml - 2007.11.12 - material didatico do curso 1 de uml.zip : Material didático do primeiro curso de UML no cliente Targettrust, oferecido no período de novembro de 2007.

Arquivos recebidos do cliente

Algumas vezes, o cliente oferece alguns arquivos para a equipe de desenvolvimento, de forma que esta possa ter mais subsídios para o trabalho.

Todos os arquivos emitidos pelo cliente devem ficar armazenados em um único local no projeto do cliente.

O nome desse local é o diretório "recebidos", o qual existe no diretorio-raiz de cada projeto do cliente.

Na eventualidade de muitos tipos diferentes de arquivos (áreas do projeto) existirem, é possível subdividir o diretório acima em outros subdiretórios, garantindo a independência de informações ao mesmo tempo em que se preserva a unicidade de localização desses artefatos (recebidos) do cliente.

Exemplo:

+-trunk...............................Diretorio principal, com artefatos em desenvolvimento ou producao.
  +-projetoX..........................Raiz do projeto do cliente
     +-fontes.........................Um diretorio qualquer
     +-docs...........................Outro diretorio qualquer
     +-recebidos......................Diretorio-base com artefatos recebidos do cliente
        +-analise.....................Artefatos recebidos em relacao a area de analise
        +-redes.......................Artefatos recebidos do cliente em relacao ao ambiente de rede
        +-emails......................Emails trocados ou recebidos do cliente

Artefatos não padronizados obtidos do restante da equipe ou empresa

Outras vezes, devido ainda a empresa como um todo não estar padronizada, parte das equipes podem utilizar convenções de nomes diferentes das apresentadas aqui. Nesse caso, ao serem colocados no repositório versionado, os arquivos devem ser adicionados com o nome conforme o formato apresentado aqui e sufixados com "(" $nomeOriginal ")". Por exemplo:

3layer - adapit - plugin jira - documento de visao (esboco do projeto).odt

Nesse exemplo, o nome "esboco do projeto" era o nome dado por um possível analista para o projeto de plugin da ferramenta Jira. Entretanto, como se percebe, esse nome não é unívoco (em outras palavras, se ele fosse recebido de maneira "ad hoc" em um email, dificilmente se saberia de qual cliente ou projeto (exceto abrindo-o) esse arquivo faria parte). Assim, esse nome foi colocado no padrão especificado pelo 3PUP, e então o nome original mantido entre parênteses para fins de referência e indexação.

.