Documente soluções de TI com centros de informações Eclipse customizados, Parte 1: Crie seu primeiro centro de informações

Recapitule e distribua sua experiência em projetos de TI para auxiliar os clientes, colegas e os seus próprios registros. Documente a solução que você implementou rapidamente e produtivamente. Agregue, organize e compartilhe apresentações, demos, documentações de produtos, feeds, amostras de código e outras informações que tenha criado ou reutilizado para distribuição em um centro de informações baseado em Eclipse.

Tricia York Garrett, Information Architect, IBM  

Tricia York GarrettTricia York Garrett é uma arquiteta de informações para a equipe de documentação do IBM WebSphere Application Server. Ela tem co-liderado um grupo de trabalho interno para explorar abordagens simples e escaláveis para permitir que indivíduos e equipes documentem seus projetos de TI mais facilmente e com maior qualidade. Ela reuniu os requisitos de especialistas em soluções de TI para iniciar o desenvolvimento do Toolkit for Custom and Reusable Solution Information.



04/Mar/2010

Visão Geral

A implementação de uma solução de TI envolve a integração e customização de vários componentes de hardware e software. A documentação correspondente e as outras informações técnicas usadas na compilação de um "guia de cuidados e alimentação" sobre a solução implementada podem envolver vários autores, locais e formatos de documentos — desde teamrooms tradicionais e documentos de escritório até fóruns, blogs e wikis. Reunir, organizar e distribuir a documentação ao seu cliente (ou chefe, ou equipe) pode ser algo trabalhoso, principalmente se a criação de documentações não for sua especialidade principal. A alternativa é oferecer uma documentação inadequada, o que apresenta suas próprias desvantagens, como os custos de suporte, produtividade desperdiçada e confiança do cliente desgastada.

Este artigo introduz um kit de ferramentas que ajuda indivíduos ou equipes de projetos a acelerarem a tarefa de documentação de uma solução de TI. Se fazer uma rápida lista de links ou compilar um arquivo ZIP de documentos úteis é sua abordagem costumeira para a documentação de uma solução de TI, pense em gastar um tempo parecido para semear um centro de informações de soluções que possa crescer progressivamente e elegantemente ao longo do ciclo de vida da solução, incorporando tecnologias como feeds RSS para manter as informações atualizadas.

O kit de ferramentas agrega boas práticas para o design, arquitetura e distribuição de informações em modelos e rotinas automatizadas, o que significa que ele não requer qualificações em experiência do usuário, desenvolvimento de informações ou codificação de plug-ins do Eclipse. O kit de ferramentas é implementado na plataforma rich client Eclipse, além de produzir plug-ins de documentação padrão do eclipse, mas não é necessário instalar um ambiente de desenvolvimento integrado como o Eclipse para usar o kit de ferramentas.

Forneça ao cliente um centro de informações portátil e independente que possa ser visualizado em um desktop local ou remoto, em uma intranet, ou na Internet. Como mostrado na Figura 1, o título do navegador, a página inicial e a navegação do centro de informações podem ser customizados para uma solução específica.

Figura 1. Kit de capacitação Project Zero WebSphere sMash
Kit de capacitação Project Zero WebSphere sMash

Se você fornecer o centro de informações da solução e o projeto usado para criá-lo, o beneficiário pode ampliar o centro de informações com mais documentações ao longo do ciclo de vida da solução. O kit de ferramentas para desenvolver e atualizar centros de informações de soluções customizados está disponível gratuitamente no IBM® alphaWorks.

O método: Um kit de ferramentas com uma simples interface gráfica com o usuário

O Toolkit for Custom and Reusable Solution Information, disponível no alphaWorks, ajuda você a construir um centro de informações para entregar ao cliente, ou para compartilhar com os colegas de equipe. Iniciar um projeto de informações de solução exibe uma árvore de navegação gráfica, à qual é possível arrastar e soltar informações, como arquivos de apresentação. Em breve, você possuirá os ingredientes de um centro de informações de solução orientado a tarefas, sem precisar de qualificações em desenvolvimento de informações ou experiência do usuário. É possível exportar um centro independente que possa ser executado pelo cliente em um desktop, em uma intranet ou na Internet.

O kit de ferramentas permite que você:

  • Faça o acompanhamento das informações originais e reutilizadas para documentar sua solução de TI
    • Procure conteúdo online, capturando-o para reutilização.
    • Acumule sua própria biblioteca pessoal de conteúdo: links, feeds, consultas e documentos úteis
    • Compartilhe bibliotecas de conteúdo com os outros através da importação ou exportação de conteúdo
    • Reutilize o conteúdo em vários centros de informações customizados.
  • Agregue as informações a centros de informações de soluções bem organizados.
    • Organize conteúdo no melhor modelo de navegação
    • Crie e compartilhe modelos de visualização de navegação com a sua equipe
    • Customize o centro de informações de solução para um público específico, como um cliente
    • Crie uma fachada unificada para um conjunto de apresentações, demos e outras informações
    • Visualize centros de informações customizados de forma fácil e iterativa
  • Ofereça centros de informações de soluções para clientes e outros interessados
    • Exporte arquivos ZIP para entrega aos clientes
    • Execute centros de informações no seu desktop com suporte para visualização remota
    • Hospede centros de informações em uma intranet
    • Exporte projetos de informações de soluções, permitindo que outras pessoas os reutilizem ou expandam

A tecnologia: Sistemas baseados em Eclipse

O Eclipse Platform inclui seu próprio sistema de ajuda, baseado em um sumário em XML que faz referência a arquivos HTML, como descrito em Documenting your project using the Eclipse help system. O sistema de ajuda não precisa ser integrado como parte de uma interface com o usuário de software. Na verdade, o sistema de ajuda pode ser executado independentemente. Ele pode ser entregue uma única vez, e então alternado facilmente entre hospedagem no desktop e intranet ou na Internet. Essas características tornam o sistema de ajuda do Eclipse um meio conveniente para a distribuição de um site de documentação completamente independente e auto-suficiente (conhecido como centro de informações).

O Toolkit for Custom and Reusable Solution Information torna o poderoso sistema de distribuição de informações baseado em Eclipse mais disponível para todos, mesmo aqueles que não são desenvolvedores de software ou de Web sites de informações. Ele oferece uma interface gráfica de arrastar e soltar, que permite a produção de centros de informações baseados em Eclipse que contêm qualquer conteúdo desejado, sem que seja necessário qualquer conhecimento das convenções de empacotamento de plug-ins do Eclipse.


Inicie um centro de informações de solução customizado

Pronto para criar seu primeiro centro de informações? Para começar, obtenha e instale o Toolkit for Custom and Reusable Solution Information no alphaWorks. O kit de ferramentas vem empacotado como arquivo ZIP. A instalação do kit de ferramentas é tão simples quanto a extração do conteúdo do arquivo ZIP. Em seguida, abra o kit de ferramentas e prossiga à área de trabalho onde você poderá iniciar um projeto de informações de solução.

Para iniciar um projeto de informações de solução:

  1. Clique duas vezes no arquivo run.bat para iniciar a interface gráfica do kit de ferramentas.
    Figura 2. Clique duas vezes em run.bat para iniciar o kit de ferramentas
    Clique duas vezes em run.bat para iniciar o kit de ferramentas
  2. Quando a tela de boas-vindas do kit de ferramentas for exibida, clique no botão para o Workbench, como mostrado na Figura 3. Observe que estão disponíveis outros botões para ler um resumo geral, encontrar tutoriais e mais.
    Figura 3. Tela de boas-vindas com o botão Workbench selecionado
    Tela de boas-vindas com o botão Workbench selecionado
  3. Inicie um projeto, que corresponde a um centro de informações de solução.
    1. Selecione a informação de projeto em File > New > Solution no menu. Será exibida uma caixa de diálogo de novo projeto de informações de solução.
    2. Especifique um nome de projeto, como "Solução de computação em nuvem para J.K. Enterprises."
    3. Clique em Finish.

É exibido um modelo de visualização de navegação que pode ser customizado e preenchido com conteúdo.


Customize a visualização de navegação para seu centro de informações

O modelo padrão de visualização de navegação engloba as melhores práticas para a documentação de uma solução de TI de maneira completa e organizada. Porém, como mostrado no centro de informações de solução na Figura 1, é possível alterar a visualização de navegação padrão para se adequar às suas necessidades. Por motivos descritos mais adiante, é recomendável evitar a exclusão de seções da visualização de navegação padrão que possam ser relevantes à sua solução mais tarde, mesmo após dias, meses ou anos, à medida que a solução evolui ao longo do seu ciclo de vida.

Para customizar o texto no modelo de visualização de navegação para seu projeto específico:

  1. Selecione uma seção do modelo de navegação (uma caixa amarela), como "My Solution." Ela se tornará amarela.
  2. Clique duas vezes na entrada para ativar a edição do seu rótulo.
  3. Altere o texto do rótulo, como "Solução de computação em nuvem para J.K. Enterprises". (O número 0 no início da entrada de navegação é exibido enquanto a visualização de navegação estiver sendo editada, mas não será exibida no seu centro de informações de solução).
  4. Para salvar sua alteração na entrada de navegação atual, selecione uma entrada de navegação diferente.
Figura 4. Customizando a visualização de navegação
Customizando a visualização de navegação

Experimente arrastar e soltar as seções de navegação para reorganizar a visualização de navegação. Também é possível adicionar e excluir seções de navegação. O menu exibido ao clicar duas vezes em uma seção de navegação oferece uma maneira conveniente de customizar a visualização de navegação.


Reúna o conteúdo que deseja incluir

Pense no conteúdo original e reutilizado que você deseja reunir e apresentar de forma integrada em uma única visualização de navegação. Identifique arquivos, como amostras, multimídia e documentos de escritório. Pense em wikis ou Web sites internos ou externos, ou em bancos de dados do IBM Lotus Notes® com conteúdo para captura.

Tipos de conteúdo suportados pelo kit de ferramentas

  • Arquivos: Documentos locais, como apresentações, planilhas, demonstrações e amostras de código
  • Conteúdo da Web: Links para páginas da web, ou cópias locais dessas páginas feitas pelo kit de ferramentas
  • Feeds: Feeds RSS e ATOM para ajudar os usuários a encontrar o conteúdo mais recente
  • Notas: Documentos exportados pelos teamrooms do Lotus Notes, ou links para documentos em interfaces da Web do Notes
  • Livros: Plug-ins de documentação do Eclipse, que são unidades de pacote reutilizáveis que podem ser lidas pelos centros de informações

Depois de notificar o kit de ferramentas sobre um documento ou página da Web pela primeira vez, o documento ou página da web torna-se disponível para uso em vários projetos de informações de solução. O kit de ferramentas suporta muitas maneiras de coletar conteúdo para sua biblioteca de conteúdo:

  • Procurar conteúdo no site IBM.com e capturá-lo
  • Importar e exportar bibliotecas de conteúdo para compartilhar com outros usuários do kit de ferramentas
  • Importar plug-ins do sistema de ajuda do Eclipse, o pacote padrão para documentações de produtos IBM
  • Importar visualizações do Lotus Notes que tenham sido exportadas a partir do Notes em formato XL
  • Usar caixas de diálogo de configuração para adicionar documentos individuais

Comece usando a caixa de diálogo de configuração para adicionar um arquivo do seu sistema de arquivos local.

  1. Procure um arquivo (qualquer arquivo serve):
    1. Selecione Window > Show View > Files na barra de menu. A página tabulada Files é trazida ao primeiro plano, como mostrado na Figura 5. Observe que há outras páginas tabuladas para adicionar outros tipos de conteúdo.
      Figura 5. Adicionando arquivos
      Adicionando arquivos
    2. Clique no botão Add Files.
    3. No assistente Files, mantenha "default" como o grupo. Os grupos funcionam como um conjunto de gavetas nas quais o conteúdo é organizado e armazenado.
    4. Especifique um nome para exibir na navegação, como "Visão geral da computação em nuvem" se esse nome descrever seu arquivo.
    5. Clique em Browse e use a caixa de diálogo de pesquisa para localizar o documento no seu sistema de arquivos.
    6. Quando retornar ao assistente Files, clique em Next.
  2. Especifique as informações da página que introduzirão o arquivo aos usuários:
    1. Especifique o título que será exibido na página HTML que o kit de ferramentas gerará para dar informações sobre o arquivo aos leitores do centro de informações.
    2. Especifique uma descrição para ajudar os usuários a decidirem se visualizarão ou não o arquivo.
    3. Facultativamente, especifique o publicador, que pode ser você, sua companhia, o autor do arquivo ou qualquer outro valor que desejar.
    4. Especifique as palavras-chave que estarão disponíveis para a procura do centro de informações.
    5. Clique em Finish. Seu arquivo será relacionado no grupo padrão na página tabulada de arquivos.

Customizando arquivos reutilizados

Após capturar um arquivo no kit de ferramentas, é possível editá-lo diretamente de dentro do kit. Localize o arquivo na página tabulada Files. Clique com o botão direito do mouse no arquivo e selecione Edit with... para exibir as opções de editor. O editor padrão geralmente é o editor definido no seu sistema operacional Windows®. Quando salvar o arquivo, você estará salvando a versão customizada para reutilização em qualquer um dos seus projetos de centros de informações de soluções.


Preencha a visualização de navegação com conteúdo

Todas aquelas páginas tabuladas na Figura 5 compõem a sua biblioteca de conteúdo. É possível arrastar e soltar conteúdo, como um arquivo, na visualização de navegação a partir da sua biblioteca de conteúdo.

Para adicionar seu arquivo à visualização de navegação:

  1. Certifique-se de que está visualizando a página tabulada Files.
  2. Verifique se está visualizando arquivos no grupo de conteúdo padrão.
  3. Localize seu arquivo no grupo de conteúdo padrão.
  4. Clique no seu arquivo. Arraste e solte o arquivo na visualização de navegação, onde ele é representando por uma nova seção de navegação.

Por exemplo, a Figura 6 mostra como um arquivo chamado Product presentation é exibido quando ele é incluído na página tabulada Files, assim como quando ele é arrastado e solto na visualização de navegação. A Figura 6 também mostra o uso do grupo "sample project", que foi preenchido com vários arquivos. (A propósito, o botão Add Group fica a poucos botões de distância do botão Add Files usado anteriormente).

Figura 6. Adicionando conteúdo à visualização de navegação
Adicionando conteúdo à visualização de navegação

Customize o título do navegador e a página inicial do centro de informações

O centro de informações é exibido em um navegador da Web, seja ele executado em um desktop, em uma intranet ou na Internet. O nome do centro de informações é exibido na barra de título do navegador da Web.

Para customizar o nome do centro de informações que será exibido na barra de título do navegador:

  1. Selecione Information Center > Browser Title no menu do kit de ferramentas.
  2. Especifique um título de navegador, como "Solução de computação em nuvem para J.K. Enterprises."
  3. Clique no "X" da página tabulada Browser Title para salvar as alterações e sair.

O centro de informações precisa de uma página inicial para informar os usuários sobre a solução. Essa é a primeira página exibida quando os usuários visualizam o centro de informações. O kit de ferramentas gerará uma página inicial com base nas informações que você fornecer.

Para customizar a página inicial do centro de informações:

  1. Selecione Information Center > Home Page no menu.
  2. Especifique um título de página, como "Solução de computação em nuvem para J.K. Enterprises."
  3. Especifique várias informações, sendo todas elas opcionais.
  4. Clique no "X" da página tabulada Home Page para salvar as alterações e sair.
Figura 7. Fornecendo informações para gerar uma página inicial
Fornecendo informações para gerar uma página inicial

A Figura 8 mostra a página inicial gerada que corresponde às informações fornecidas na Figura 7.

Figura 8. Visualizando a página inicial gerada
Visualizando a página inicial gerada

A propósito, após exportar o centro de informações a partir do kit de ferramentas, a página inicial gerada é incluída como um arquivo index.html, juntamente com um arquivo CSS (welcome.css) que permite o ajuste da aparência da página inicial. É possível ajustar os estilos de fonte, tamanhos de fonte, cores de fundo, etc.

Uma abordagem alternativa para gerar uma página inicial seria importar uma página inicial em HTML do seu sistema local. A página deve ser chamada index.html. Selecione a opção de menu Information Center > Home page, mas ao invés de preencher o modelo para gerar uma página inicial, clique no botão de rádio chamado Directory contendo a página index.html, e então siga as instruções.


Visualize seu centro de informações

Esquema invisível de navegação

Quando você visualizar seu centro de informações de solução, preste atenção na maneira como seu público só enxerga as partes da visualização de navegação nas quais você arrastou e soltou conteúdo. O resto da visualização de navegação serve como um esquema invisível ou um auxílio de planejamento. Não é necessário excluir as partes não-utilizadas.

Pode-se começar a visualizar o centro de informações customizado assim que um item de conteúdo, como um arquivo, for arrastado e solto na visualização de navegação. A visualização de navegação do centro de informações exibirá apenas as partes que forem preenchidas com conteúdo. Por esse motivo, é recomendado que não sejam excluídas as seções de navegação que possam ser úteis mais tarde, mesmo se elas não forem usadas.

Para visualizar seu centro de informações:

  1. Clique em Information Center > Preview na barra de menu.
  2. Espere até o centro de informações ser exibido. Veja o status na área de Console junto à parte de inferior do kit de ferramentas.
  3. Quando o centro de informações for exibido, experimente a árvore de navegação e os recursos de procura.
  4. Clique no "X" na página tabulada Preview quando tiver terminado a visualização.
Figura 9. Visualizando o centro de informações
Visualizando o centro de informações

Perceba, examinando a Figura 9, que o kit de ferramentas gera várias páginas HTML para exibir as informações fornecidas por você sobre os arquivos e outros itens na sua biblioteca de conteúdo. As páginas incluem um gráfico marcador (site.gif) que pode ser substituído por um gráfico de sua preferência. Por exemplo, é possível substituir o gráfico de seta próximo a Product presentation na Figura 9 pelo logotipo do projeto ou da companhia. Espere até exportar o centro de informações para distribuição, e então substitua o gráfico.

Dica de resolução de problemas: Se a qualquer momento o kit de ferramentas travar ou parar de responder, não hesite em fechá-lo usando o "X" no canto superior direito do kit. Clique em OK para qualquer mensagem dada pelo kit de ferramentas. O kit voltará a funcionar normalmente quando for reiniciado. Esse comportamento é mais comum em conjunto com a visualização de centros de informações.


Distribua seu centro de informações

Exporte o centro de informações quando estiver pronto para distribuí-lo ao público. A qualquer momento, é possível continuar a trabalhar no projeto de informações de solução e exportar suas versões subsequentes.

Para exportar o centro de informações:

  1. Clique em Information Center > Export na barra de menu.
  2. Na caixa de diálogo resultante de informações de solução de pacote, especifique o destino para o centro de informações exportado. Clique em Finish.
  3. Continue a usar o kit de ferramentas para outras atividades enquanto seu centro de informações é exportado como um arquivo ZIP.

Teste seu centro de informações distribuído

Teste as etapas que serão seguidas pelo beneficiário do seu centro de informações de solução

  1. Extraia o centro de informações de solução do arquivo *_package.zip.
  2. Navegue até o diretório que contém o arquivo em lote para iniciar o centro de informações, IC_start.bat.
  3. Envie o arquivo IC_start.bat para um editor de texto, como o Bloco de notas.
  4. Facultativamente, verifique o argumento -port, por exemplo -port 8888. Faça o ajuste para uma porta diferente se necessário.
  5. Feche o arquivo IC_start.bat. Clique duas vezes em IC_start.bat para executar o arquivo. Uma janela de comando do sistema é exibida para mostrar o progresso.
  6. Use um navegador da Web para visualizar o centro de informações.
    • (Opcional) Teste o centro de informações no seu próprio desktop, navegando em: http://localhost:8888/help/index.jsp
    • Teste a visualização remota do centro de informações, navegando em: http://your.host.name:8888/help/index.jsp

Clique duas vezes em IC_end.bat e feche a janela do navegador quando quiser desligar o centro de informações.

A Figura 10 mostra um exemplo de centro de informações de solução no qual uma demonstração está sendo executada.

Figura 10. Exemplo de um centro de informações criado com o kit de ferramentas
Exemplo de um centro de informações criado com o kit de ferramentas

Conclusão

Você acabou de criar seu primeiro centro de informações. Use o kit de ferramentas para criar um centro de informações completo, ou comece pequeno e passe alguns minutos reunindo documentos no seu kit de ferramentas para uma distribuição apresentável, duradoura e extensível. A decisão de lapidar a aparência do centro de informações ou mantê-lo como "um diamante bruto" depende inteiramente das suas necessidades comerciais. Aproveite!

Recursos

Aprender

Obter produtos e tecnologias

Discutir

  • Os newsgroups do Eclipse Platform devem ser sua primeira parada para tratar de perguntas sobre o Eclipse. (Se selecionar esse link, seu aplicativo padrão de leitura de notícias Usenet será iniciado e o endereço eclipse.platform será aberto.)
  • Os newsgroups do Eclipse têm muitos recursos para aqueles interessados em usar e estender o Eclipse.
  • Participe dos blogs developerWorks e envolva-se na comunidade do developerWorks.

Comentários

developerWorks: Conecte-se

Los campos obligatorios están marcados con un asterisco (*).


Precisa de um ID IBM?
Esqueceu seu ID IBM?


Esqueceu sua senha?
Alterar sua senha

Ao clicar em Enviar, você concorda com os termos e condições do developerWorks.

 


A primeira vez que você entrar no developerWorks, um perfil é criado para você. Informações no seu perfil (seu nome, país / região, e nome da empresa) é apresentado ao público e vai acompanhar qualquer conteúdo que você postar, a menos que você opte por esconder o nome da empresa. Você pode atualizar sua conta IBM a qualquer momento.

Todas as informações enviadas são seguras.

Elija su nombre para mostrar



Ao se conectar ao developerWorks pela primeira vez, é criado um perfil para você e é necessário selecionar um nome de exibição. O nome de exibição acompanhará o conteúdo que você postar no developerWorks.

Escolha um nome de exibição de 3 - 31 caracteres. Seu nome de exibição deve ser exclusivo na comunidade do developerWorks e não deve ser o seu endereço de email por motivo de privacidade.

Los campos obligatorios están marcados con un asterisco (*).

(Escolha um nome de exibição de 3 - 31 caracteres.)

Ao clicar em Enviar, você concorda com os termos e condições do developerWorks.

 


Todas as informações enviadas são seguras.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=80
Zone=Software livre
ArticleID=471470
ArticleTitle=Documente soluções de TI com centros de informações Eclipse customizados, Parte 1: Crie seu primeiro centro de informações
publish-date=03042010