Documentando projetos com o Daux.io

() translation by (you can also view the original English article)

Final product image — What You'll Be Creating

Documentar um projeto pode ser uma tarefa árdua, mas não ser. Existe algumas ferramentas por ai para fazer este trabalho - eu geralmente utilizo o Daux.io por causa da sua flexibilidade.

Neste artigo vou mostrar porque você deve documentar seus projetos, e como utilizar o Daux.io para tal.

Porque a documentação é necessária

Escrever uma documentação para o seu projeto pode ser a decisão individual mais importante que você ter. A razão pela qual documentações geram desconfortos em projetos web é porque não há tanto em jogo.

Vamos pegar um Boeing 787 como exemplo. Esse produto tem uma ampla documentação baseada no corpo cobrindo qualquer aspecto do design até a manutenção. Inclusive existe um manual de 150 páginas documentando 787 características que devem ser consideradas ao planejar aeroportos.

Porque um avião tem uma senhora documentação e um website não?

Acredito nestas três principais razões:

Tem muito dinheiro envolvido
Questões de segurança
questões de escalabilidade

Websites raramente abordam questões de segurança, mas assim que aumentar o tráfego e o dinheiro começar a surgir, pode ter certeza que a documentação vai aparecer. Projetos grandes como o Twitter ou Facebook tem uma quantidade considerável de informações disponível para desenvolvedores, internamente e publicamente.

Websites com um tráfego considerável também acabam decidindo criar uma documentação para seus projetos. A ideia é que se alguém precisar fazer alguma notificação, a documentação esteja disponível como referência. Isso poupa tempo e consequentemente dinheiro.

Isso significa que você não precisa um documentação para projetos menores? Claro que precisa, a questão é: deveria?

Os benefícios da documentação

A documentação garante referências padrões para um projeto. Os benefícios são bem óbvios quando se trabalha em equipe, mas quando se trabalha sozinho pode ser bem dificeis de notar.

Se você garante o pão de cada dia criando websites, as chances são que você crie pelo alguns por ano. Você por acaso se lembra como um website tweeta automaticamente seu conteúdo quando você voltar a rever ele, em agosto? E se uma empresa solicitar que você encaminhar o projeto para outro desenvolvedor? Você pode gastar uma hora em cada manhã respondendo questões sobre seu código para o próximo mês.

Até o programador mais consistente é inconsistente. Com o crescimento e aprendizado. a tendência é melhorar a maneira de trabalhar. Digamos que você introduziu o Gulp no seu workflow, ou então que você começou a utilizar PHP orientado a objeto.

Uma documentação também pode esclarecer situações que podem não parecer tão obvias olhando direto o código. Você pode escolher uma solução alternativa, pelo simples fato de alguém ter questionado fazer algo rápido, e no final os fins justificam os meios. Isso pode ser adicionado a documentação, pelo menos como uma tarefa para atualizar mais tarde.

Documentando com o Daux.io

O Daux.io pode assustar algumas pessoas inicialmente porque ele não é apenas HTML, e só pode ser visualizado utilizando um servidor. De qualquer forma, configurar tudo pode ser um pouco cansativo, mas assim que você termina, a utilização é mais simples e fácil.

Introdução ao Daux.io

A maniera mais fácil de utilizar o Daux.io é baixando seu repositório através do GitHub. Você pode baixar o pacote clicando no botão Download ZIP na lateral direita. Se você manjar do GitHub, você pode clonar o repositório, ou até mesmo pegar via composer com o Packagist.

Se você baixou do GitHub, o resultado vai ser uma pasta com o nome "daux.io-master".

Renomeie a pasta para "documentation" e mova para a área de trabalho, apenas para facilitar. Para escrever sua documentação você não precisa de nada. Você pode editar os arquivos Markdown em qualquer editor e depois utilizar um comando para converter tudo para HTML e facilitar o compartilhamento. De qualquer forma, é melhor conferir o trabalho enquanto executamos, então vamos nos preparar.

Visualizando a documentação

Para visualizar a documentação vamos precisa de um servidor. Para facilitar, tudo que precisamos já vem no repositório do Daux.io que baixamos, precisamos apenas de alguns pré requisitos para iniciar o servidor: npm e Grunt.

Instalando o npm e o Grunt

A maneira mais simples de utilizar o npm (Node Package Manager/Gerenciador de pacotes do Node) é instalando o NodeJS. Acesse o site do NodeJS e faça download do instalador. Uma vez instalado você ele permite utilizar o npm no terminal (Linux/OSX) ou no prompt de comando (Windows).

Nota: vou tratar tanto o prompt do comando do Windows quanto o terminal do Linux/OS X com a mesma palavra: terminal.

O próximo recurso que vamos precisar é o Grunt. O Grunt é instalado via npm, então, caso você tenha já completado o ultimo passo, este vai ser bem simples. Abra o terminal e digite o seguinte comando:

1	npm install -g grunt-cli

Agora temos as ferramentas necessárias para começar. Se o npm é novo para você, e você é desenvolvedor web, recomendo, e muito, se aprofundar mais na solução. Ele permite instalar ferramenta de maneira bem fácil, e você nem precisa conhecer o Node.js para utilizar seus recursos (como o Grunt, por exemplo).

Os procedimentos executados até agora só são necessários caso você não tenha as ferramentas necessárias instaladas. Não importa quantas instâncias de documentações do Daux.io você tem, você só vai precisar instalar o npm e o Grunt uma vez.

Dica: se quiser se apronfundar mais nas ferramentas de linha de comando, acompanhe a série de tutoriais The Command Line for Web Design do Kezz Bracey.

Usuários do Windows: instalando PHP

Os passos a seguir são apenas para usuário Windows, o OS X e a maioria das distros do Linux já vem com o PHP pré instalado, então, quem utiliza uma dessas plataformas pode pular essa seção. Infelizmente, instalar a linha de comando PHP no Windows pode ser um pouco chato, mas vamos aos procedimentos.

Vá até a página de download do PHP e baixe a versão estável disponível. Eu utilizei a versão "VC11 x86 Non Thread Safe" quando testei. Baixei o arquivo e extrai o conteúdo para a raiz da unidade C:/, e renomeei a pasta para "php". No fim do processo vamos ter uma pasta chamada "php" no diretório C:/, com o arquivo "php.exe" dentro.

Agora, precisamos garantir que os comandos PHP estão operando em qualquer ambiente. No Windows 7, a maneira mais simples de garantir o funcionamento do PHP, é clicar com o botão direito no Computador e selecione Propriedades. Clique na guia Configurações Avançadas na barra lateral direita. Clique na guia Avançado, depois no botão Variáveis de Ambiente.

Clique no item path e depois no edit. No fim do valor especificado, vamos adicionar um caminho de referência: “C:\Users\Dani\environment”. Deve ser uma pasta do próprio usuário. Feito isso, salve tudo e crie essa pasta. (Se você utiliza uma versão diferente do Windows, de uma olhada no Computerhope, nele tem o procedimento para diferentes versões do sistema).

Dentro desta pasta cria um arquivo chamado "phppath.cmd". Edite este arquivo utilizando qualquer editor de texto e adicione o seguinte conteúdo:

1	PATH=%PATH%;C:\Users\Dani\environment
2	php -v

Feito isso, vá até a pasta atráves do terminal com o comando cd %userprofile%/environment e execute o seguinte comando: phppatch.

E por último, feche o terminal e abra novamente. O PHP agora deve estar disponível em todo o sistema. Vale ressaltar, que este procedimento você também só precisa executar uma vez, apenas em máquinas com sistema operacional Windows.

Configurando o Daux.io

Ainda no terminal, vá até a pasta do projeto. Lembre-se, isso deve ser feito no seu desktop. No Windows, você pode utilizar o seguinte comando para ir até a pasta do projeto:

1	cd %userprofile%/Desktop/documentation

No OS X você pode utilizar o comando:

1	cd ~/Desktop/documentation

O primeiro comando que devemos executar é o npm install. Assim que o comando completar sua ação, execute o comando npm update para ter certeza que tudo está atualizado. Esse comando instala e atualiza todas as dependências do Daux.io. Você vai precisar executar este procedimento em todas as instâncias do Daux.io que você criar.

Rodando o Preview

Finalmente estamos prontos para testar o que temos até agora da nossa documentação. Agora basta executar o comando grunt no terminal, para testarmos o que temos até então (tenha certeza que o terminal está na apontado para a pasta do projeto quando o comando for executado.

Após alguns segundos pensando você deve se deparar com algo assim:

Isso significa que o servidor está OK e operando. Uma nova aba deve abrir no navegador. Se isso não ocorrer, de uma olhada no IP apresentando proximo ao "listening on", e acesse o mesmo a partir do navegador. No meu exemplo, o IP é: "127.0.0.1:8085".

Nota: em alguns casos, o navegador pode abrir uma página com a informação "no page found" ou algum erro similar. Neste caso, recarrega a guia, o servidor pode levar um tempo para inicializar o Daux.io.

Ao acessar o endereço, você deve ver a documentação padrão no navegador. As informações que você está visualizando são geradas a partir de arquivos Markdown. Agora que podemos ver o que estamos fazendo, vamos começar a redigir a documentação.

Redigindo a documentação

Junto a pasta "documentation" deve ter uma pasta de nome "docs". Ele guarda os arquivos da sua documentação atual, todo o resto faz parte da mágica do Daux.io. O Daux.io utiliza um termo especifico para dar total controle da ordem das páginas.

Cada item na página deve começar com um número seguido de um underline "_" . Quanto maior o numero, maior o conteúdo e sua posição em relação ao fim da documentação. Se precisar de uma unica página, crie um arquivo Markdown (exemplo: 04_index_teste), se precisar de uma estrutura hierarquica de páginas, crie uma pasta (ex: 05_code_estilo).

O texto após o numero determina o nome da página na documentação. Os exemplos citados ficaram dessa forma na documentação: "Index teste" e "Code estilo". Tenha certeza de utilizar apenas caracteres alfanuméricos e underlines ( _ ), que são convertidos em espaço.

Daqui para frente tudo é bem simples, tudo que você vai precisar é continuar editando os arquivos Markdown. Se você não conhece ou não está familiarizado com arquivos Markdown, dê uma olhada no Markdown Cheatsheet. Basicamente, é uma maneira de marcar um texto (indicar titulos, links, imagens, etc.) sem utilizar códigos em HTML.

Se você deseja criar uma seção com sub-páginas, utilizando uma pasta, você pode especificar as sub-páginas da mesma maneira que fizemos antes. Com a pasta criada, crie os arquivos Markdown começando com nome seguido do número (que da ordem as páginas), e o nome que você deseja exibir.

Landing Pages

Outra coisa que o Daux.io permite fazer é criar uma landing page para as seções da sua documentação. Toda sua documentação vai ter uma landing page se você criar um arquivo "_index.md". Dê uma olhada no exemplo padrão para ter noção da formatação.

Cada sesção também pode ter uma landing page. Se uma seção não possuir uma landing page, o item do menu não vai levar a lugar algum, apenas vai apresentar uma lista dos itens da seção. Se você quer que o primeiro item tenha sua própria landing page, basta criar um arquivo "index.md" junto a pasta daquela seção.

Gerenciando várias documentações

Alguns projetos necessitam de diversas documentações. Um website pode contar uma documentação focada no usuário final da página e uma para desenvolvedores, com informações totalmente diferentes.

Uma maneira de gerenciar tantas documentações, com o Daux.io, seria criando várias instâncias do mesmo. Isso implicaria na necessidade de outro servidor e configurações adicionais. Graças a deus existe uma maneira mais eficaz!

Dê uma olhada no arquivo "global.json" na pasta principal da documentação. Se você abrir o arquivo em um editor de texto você vai notar que o parametro docs_directory aponta para docs. Crie uma cópia do diretório, renomeie o mesmo para "user_docs" e adicione alguns arquivos para que permita a execução sem utilizar os arquivos da documentação original.

Agora altere o parâmetro no docs_directory para user_docs e carregue a página da documentação novamente no navegador. Você agora está vendo o conteúdo da nova pasta. Assim fica fácil manipular várias documentação, sem precisar reiniciar o servidor ou utilizar várias instâncias do Daux.io.

Gerando a documentação final

Claro que ao fim do dia, precisamos distribuir a documentação ao publico. A melhor forma de fazer isso é utilizando o formato HTML, o Daux.io tem suporte para converter a documentação! No terminal, no diretório da documentação, execute o seguinte comando:

1	php generate.php

Feito isso será criada uma pasta com todos os arquivos HTML e adendos necessários para visualizar a documentação. Você pode compactar a pasta e enviar para os interessados ou subir para um servidor e exibir na internet.

Configuração de projeto avançado

Existem varios recursos que você pode controlar através do arquivo "default.json". Por padrão existe um link com informações como Made by Todaymade junto a links para seguir do Twitter, que você pode ou não customizar para o seu projeto. A página principal do Daux.io lista as opções que você pode utilizar, na parte "Configuration", mais abaixo na página. . .

Você pode utilizar "twitter": ["seunomenotwitter"] para adicionar seu link para o Twitter, por exemplo. Links podem ser controlados utilizando o parâmetro links, conforme o exemplo:

"links": {
    "GitHub Repo": "https://github.com/yourgithubrepo",
    "Support": "http://support.myproduct.com",
    "Made by Me": "http://mywebsite.com"
}

Você pode conferir todas as opções dos parametros de configuração na página principal do Daux.io. Segue um exemplo do arquivo "default.json" para um projeto imaginário.

{
    "title": "My Project",
    "tagline": "My Stylish Documentation",
    "docs_directory": "docs",
    "valid_markdown_extensions": ["md", "markdown"],
    "repo": "danielpataki/exampleproject",
    "twitter": ["danielpataki"],
    "theme": "daux-blue",
    "breadcrumbs": false,
    "template": "default",
    "clean_urls": false,
    "toggle_code": false,
    "date_modified": false,
    "float": false,
    "links": {
        "GitHub Repo": "https://github.com/danielpataki/exampleproject",
        "Support": "http://support.exampleproject.com",
        "Made by Daniel": "http://danielpataki.com"
    }
}

Conclusão

Configurar o Daux.io pode parecer complicado em um primeiro momento, mas não chega tanto, especialmente se você utilizar sistemas Mac ou Linux, onde os recursos necessários já estão pré instalados. Se você não está acostumado com o terminal e servidores locais, pode levar um tempo até se acostumar com o ambiente, mas assim que pegar a prática tudo vai ficar mais claro.

Assim que você testar o Daux.io você vai notar que ele é bem simples e fácil de utilizar, além de ser bem flexível e de fácil manutenção. O projeto, seu cliente, e outros colaboradores e usuários vão agradecer a você pelo esforço de criar e manter a documentação, em contra partida, você vai ter mais tempo para focar no projeto ao invés do suporte a usuário.

Seja o primeiro a saber sobre novas traduções–siga @tutsplus_pt no Twitter!