Documentando de forma Ágil (usando dokuwiki)

WIKI Documentado de forma ágil.

José Augusto (Guto) [email protected]

@gutocarvalhoTuesday, April 24, 12

mailto:[email protected]


Agenda

Entendendo Wiki

Sintaxe

Estrutura

Administração

Controles de Acesso46 Slides - 60 a 80 Minutos

Tuesday, April 24, 12

Entendendo Wiki


Wiki: O que significa?

Os termos wiki (pronunciado /uíqui/ ou /víqui/) e WikiWiki são utilizados para identificar um tipo específico de coleção de documentos em hipertexto ou o software colaborativo usado para criá-lo.

O termo "Wiki wiki" significa "extremamente rápido" no idioma havaiano.

Fonte: http://pt.wikipedia.org/wiki/Wiki


http://pt.wikipedia.org/wiki/Hipertexto

http://pt.wikipedia.org/wiki/Hipertexto

http://pt.wikipedia.org/wiki/Software_colaborativo




http://pt.wikipedia.org/wiki/Wiki_wiki

http://pt.wikipedia.org/wiki/Wiki_wiki

http://pt.wikipedia.org/wiki/Idioma_havaiano

http://pt.wikipedia.org/wiki/Idioma_havaiano

http://pt.wikipedia.org/wiki/Wiki

http://pt.wikipedia.org/wiki/Wiki

Para o SysAdmin/DevOps qual parte da documentação é a mais importante?


Textos c/ Perfumarias?Formatação complexa?

Design refinado?Formato fechado?

Isso realmente importa?


Nada disso importa, o que importa é o conteúdo.


Necessidades do Sysadminencontrar a informação de forma simples e rápida

entender a informação para que ela lhe seja útil

ter condições de modificar a informação com objetivo de complementar, atualizar ou corrigir.

editar a informação de forma simples e rápida


Acesso através de qualquer navegador/OS

Formatação do texto em linguagem MarkDown

Edição coletiva/colaborativa (equipe)

Rastreamento de mudanças (versionamento)

Foco no conteúdo (editor sem distrações)

Portabilidade do conteúdo (texto puro)

Wiki: Características


Wiki: Projetos conhecidos

MediaWiki (site da wikipedia)

Dokuwiki (site de documentação zabbix)

MoinMoin (site de documentação projeto apache)


Wiki: Listagem de projetos

No site wikimatrix.org você irá conhecer diversas ferramentas wiki, neste site você terá condições de avaliar os recursos e as principais diferenças entre estes sistemas.

O site concentra informações referentes a grande maioria dos sistemas wiki open-source conhecidos hoje.


Nossa escolha: DokuwikiTuesday, April 24, 12

Dokuwiki: Características 1Aplicação escrita em PHP

Não usa banco de dados

Velocidade no uso (por não usar banco de dados)

Sintaxe de formatação simples (markdown)

Suporte a plugins PHP (muitos plugins disponíveis)

Suporte a categorização por namespaces


Dokuwiki: Características 2Suporte a links interwikis (wikipedia/dokuwiki)

Upload de imagens e uso de referências externas

Buscas ‘FullText Search’ com índices

Interface Agradável com recursos Ajax

Cache de Páginas

Suporte a autenticação Local, LDAP, AD, MySQL e PostgreSQL


Dokuwiki: Características 3

Suporte a mais de 50 idiomas

Código Fonte Aberto

Processo de desenvolvimento bem documentado

Syndication (RSS/ATOM) das mudanças recentes

Outros ... (http://www.dokuwiki.org/features)


http://www.dokuwiki.org/features

http://www.dokuwiki.org/features

Dokuwiki: Diferencial

O grande diferencial deste projeto é o fato de [não] utilizar base de dados relacional, tudo é salvo em arquivos no

File System.



O fato de não usar banco de dados, proporciona grande velocidade nas rotinas de criação, edição e leitura das páginas wiki, afinal, os dados são consumidos diretamente do filesystem, a aplicação faz a leitura de arquivos (.txt) em formato ASCII, algo simples, rápido, eficiente e universal.



Backup simplificado, basta compactar o diretório do dokuwiki para termos todos os dados salvos. Além disto, cada página é um arquivo de texto (.txt) simples, ou seja, nem precisamos ter um servidor de aplicação instalado para ler os dados, qualquer editor de texto puro consegue ler os dados.


Sintaxe


Linaguagem MarkdownMarkDown é uma linguagem de marcação simples, onde você declara a formatação desejada através de símbolos, estes símbolos orientam a conversão do ‘texto puro’ para uma outra linguagem que normalmente é ((x)html). Referências: http://pt.wikiped ia.org/wiki/Markdown


http://pt.wikipedia.org/wiki/Markdown

http://pt.wikipedia.org/wiki/Markdown

====== objetivo =======

descreva de forma objetiva, de preferência em uma linha o objetivo dessa wiki para agilizar o entendimento, exemplo:

* descrever a instalação de ferramente XPTO no CentOS.

====== descrição =======

Nem sempre a descrição, mas dependendo do manual é bom investir algumas linhas contextualizando a necessidade, exemplo:

* a instalacao da ferramenta XPTO foi uma demanda motivada pelo problema XPTO e após análise resolvemos abordar essa solução.

====== procedimento =======

===== requisitos =====

pacotes/dependencias

===== instalação =====

instalando pacotes, tarballs, permissoes

===== configuração =====

configuracoes em arquivos, servicos, sub-sistemas e no própio aplicativo instalado.

===== operação =====

acesso ao aplicativo e como usar

====== referências =======

sites/links que lhe ajudaram a escrever esse documento, exemplo:

* site 1 * site 2 * site 3


Mão na Massaentendendo na prática como criar e editar wikipages


Acessando wiki

Para acesse a wiki entre em http://wiki.dominio.local

Clique em Entrar

Utilize seu usuário

Clique Dokuwiki (no topo superior direito)

Clique em Playground


http://wiki.detran.df

http://wiki.detran.df

criando página

[[playground:teste do guto|Página teste do Guto]]

[[area:nome|descrição]]


Formatação Simples

//Itálico//

__sublinhado__

**negrito**

<del> tachado <del>


Listas

Lista não ordenada

* Alface* Tomate* Cebola* Alho

Lista ordenada

- Alfredo- Bernardo- Camila- Daniel- Euclides

dois espaços no inicio da linha antes do simbolo


links

http://www.google.com

www.google.com

[[http://www.google.com | Acesse o google]]

[[wp > wiki]][[infraestrutura:modelo de projeto|Visualize o modelo de Projeto]]








Imagens

{{area:nome.png | descricao caption}}

{{url | descricao caption}}

{{wiki:fotoguto.png | Foto do Gutocarvalho}}

{{infraestrutura:racks.png | Foto dos Racks do CPD}}

{{www.site.com/logo.png | Logo do Detran}}


http://site.com/logo.png%7C

http://site.com/logo.png%7C

Tabelas

^Nome^Telefone^| Jose Augusto | 5555-5555 || Fernando | 5555-5555 |


Destacando Texto

Execute o comando (dois espaços) comando 1 comando 2

<code>conteúdo longo</code>


Conteúdo Arquivo

<file php arquivo.php>

<?php echo "hello world!"; ?>

</file>


Estrutura


Administração


Área administrativa


Gerenciamento de Plugins


Gerenciamento de Usuários


Controles de Acesso


Permissões Exemplo 1


Permissões Exemplo 2


Perguntas? (5 min)


http://gutocarvalho.net@gutocarvalho




http://gutocarvalho.net


Obrigado


http://gutocarvalho.net@gutocarvalho






Documentando de forma Ágil (usando dokuwiki)

Technology

Transcript of Documentando de forma Ágil (usando dokuwiki)