Documentar Wiki de forma ágil

WIKI
Documentado de forma ágil.

José Augusto (Guto) Carvalho
gutocarvalho@gmail.com
@gutocarvalho
Tuesday, April 24, 12

Agenda

Entendendo Wiki
Sintaxe
Estrutura
Administração
Controles de Acesso
46 Slides - 60 a 80 Minutos

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


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


Textos c/ Perfumarias?
Formatação complexa?
Design reﬁnado?
Formato fechado?

Isso realmente importa?


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


Necessidades do Sysadmin
encontrar a informação de forma simples e rápida
entender a informação para que ela lhe seja útil
ter condições de modiﬁcar a informação com objetivo de
complementar, atualizar ou corrigir.
editar a informação de forma simples e rápida


Wiki: Características
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: 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: Dokuwiki

Dokuwiki: Características 1
Aplicaçã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

Suporte 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


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)


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 simpliﬁcado, 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 Markdown
MarkDown é 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


====== 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

===== conﬁguração =====

conﬁguracoes 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 Massa
entendendo 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


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

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

criando página

//Itálico//

__sublinhado__

**negrito**

<del> tachado <del>

Formatação Simples

Lista não Lista ordenada
ordenada
- Alfredo
* Alface - Bernardo
* Tomate - Camila
* Cebola - Daniel
* Alho - Euclides

dois espaços no inicio da linha antes do simbolo

Listas

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]]

links

{{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}}

Imagens

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

<code>
conteúdo longo
</code>

Destacando Texto

<ﬁle php arquivo.php>

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

</ﬁle>

Conteúdo Arquivo

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


Obrigado
http://gutocarvalho.net
@gutocarvalho


Documentar Wiki de forma ágil

Recomendados

Recomendados

Mais conteúdo relacionado

Mais procurados

Mais procurados (20)

Destaque

Destaque (9)

Semelhante a Documentar Wiki de forma ágil

Semelhante a Documentar Wiki de forma ágil (14)

Mais de Jose Augusto Carvalho

Mais de Jose Augusto Carvalho (18)

Documentar Wiki de forma ágil