Documentar projeto

[ribeiroevandro]

Galera, boa tarde!
Como vocês fazem para documentar o projeto, digo mais na parte de front-end, no CSS e HTML, como fazem esse processo, para deixar fácil a utilização dos componentes criados por outros membros da equipe? Não sei se documentar seria o termo mais correto ou se style guide ficaria melhor, mas quero saber o processo, existe uma forma amigável e não burocrática de documentar isso?

[diessica]

A resposta é style guide, tal como você citou. Eu só complementaria com alguns termos interessantes para estudo: Live Style Guide e Style Guide-Driven Development.

Este artigo introdutório é perfeito: Style Guide Driven Development: A How To Guide To Improve your Development Workflow.

Atualmente, por exemplo, em um projeto em React, estou documentando os componentes e seus possíveis estados na interface usando a ferramenta react-styleguidist.

[felipefialho]

Cara, tivemos uma issue muito boa #129, através dela descobri o MDCSS e estou usando atualmente (está incluído no Kratos);

[edivaldolluisb]

o que é MDCSS?

[Cleysonlb]

Eu indicaria essa ferramenta para criar style Guides, é de graça e bem completa! 💃

[bernardodiasc]

Comecei a documentar meus projetos em 2 formas diferentes, uma com artigos escritos em arquivos markdown e outra com geradores que extraem blocos de comentários do fonte (JS e CSS).

Pra montar a documentação baseada nos MD (na verdade é Front Matter) escrevi um script node (experimental ainda), basicamente o script lê todos os markdowns e retorna um JSON. Junto com isso também uso outro gerador para os blocos de comentários em JS, que utiliza a mesma syntax do JSDocs e outro gerador que faz o mesmo para os comentários nos CSS (nesse uso markdown nos blocos de comentários, mas pretendo evoluir pra algo parecido com JSDocs). Esses 3 geradores retornam arquivos JSON estáticos, que consumo numa interface web feita em React, nenhum segredo, apenas um minisite de documentacao com algumas funcionalidades especiais.

De qualquer modo no minisite o conteúdo apresentado é separado em tópicos principais:

• Manuais (duas seções: JS e CSS, gerados dos comments no fonte, o conteudo aqui é ligado ao código existente, documentacao de api no caso do JS e ui toolkits no caso do CSS);
• Patterns (conteudo dos MD, descrevendo todos os padroes do projeto, incluindo styleguides, modelos de código, boas praticas, regras do projeto, etc);
• Workflow (tambem conteudo dos MD, descrevendo o fluxo do trabalho, nao tanto ligado ao código, mas muito util para a equipe e o trabalho fluirem coordenadamente);

Nota: existem de fato dezenas de soluções ótimas prontas para usar, experimentei varias, mas gosto da graça de fazer eu mesmo minhas ferramentas, for fun, not for production. :)

[bertelledani]

Como nos testes, é sempre mais fácil fazer uma documentação quando você pega um projeto do zero, mas nunca é impossível. Nos últimos dois projetos que participei tanto construindo do zero ou atualizando para uma nova versão, montei um Live Style Guide como a @diessica mostrou.

Um dos projetos foi muito bom porque atuei junto com o pessoal de UX para definir os componentes e isso facilitou bastante (tanto para mim quanto para eles) mas no outro eu já recebi as telas completas do projeto inteiro. Nesse último caso a abstração ficou por minha conta, e também é legal para ter uma visão de todos os componentes que você vai criar e organizar usando por exemplo o atomic para pensar nos átomos, moléculas e organismos. Dessa forma você consegue ir dando vida tanto para o front quanto para o style guide, mantendo tudo muito organizado.

A ferramenta que tenho utilizado é o Fabricator e gosto bastante da flexibilidade que tenho nele para criar e organizar as seções do style guide: átomos, moléculas, organismos e views. Você consegue facilmente você mostrar o markup e também uma informação sobre onde o componente pode ser utilizado. Você consegue montar templates base, utilizando os mesmos componentes da documentação, o que agiliza bastante.

Dê uma olhada também no JSdoc e no Sassdoc 😄

[felipefialho]

@bernardodiasc Não tem essa sua ferramenta aberta no GH? 😆

[bernardodiasc]

@lfeh ainda nao, o que tenho no GH são protótipos do que mencionei, por exemplo o https://github.com/bernardodiasc/memex, onde comecei a brincar com o gerador Markdown->JSON.

Pra extrair a documentação no fonte do JS uso essa lib https://github.com/documentationjs/documentation que usa a mesma DSL do JSDocs mas tem opção para retornar JSON. Pro extrator do CSS comecei a escrever uma lib, pois nao encontrei nenhuma opçao que retornasse apenas o JSON (todas que experimentei compilam direto a interface, o que nao me interessa, mas se alguem souber de alguma que faz o que o documentationjs faz, me avise por favor 😄).

O que tenho esta bastante experimental, muita coisa faltando ainda e tal. Quando tiver algo compartilharei, mas dificilmente vou fazer um produto open source bonitinho e tal. Então por soluçao pronta acho que o Fabricator que a @bertelledani mencionou faz um ótimo trabalho, semelhante ao que estou tentando fazer. Embora meu objetivo final se pareça mais com esse https://www.lightningdesignsystem.com/

O react-styleguidist que a @diessica mencionou, bem legal tambem. No caso de listagem de componentes react ainda tem esse outro https://github.com/kadirahq/react-storybook que parece bem legal. Curto muito a ideia de ter uma listagem de componentes com bastante informação, um exemplo que acho muito interessante (apenas como referencia, nao estou recomendando) é o http://registry.origami.ft.com/components

Acho que o tópico "documentação" é bem amplo. SGDD parece uma boa abordagem, porém no caso de método de direçao de desenvolvimento to gostando muito de BDD que tambem tem tudo a ver com documentação (obs. BDD não anula outros metodos como SGDD ou TDD, na verdade sao todos complementares). :)

[akfzambrana]

Eu estou começando a utilizar o sc5 de acordo com o citado neste artigo da Smashing Magazine.

Nas minhas pesquisas parei no MDCSS e quase utilizei ele, mas daí acabei achando o sc5 que é baseado no MDCSS e tem algumas vantagens extras, pois inclusive o designer consegue editar algumas coisas, fazendo com que seu StyleGuide seja muito mais completo e "vivo".

Recomendo muito a leitura do artigo, pois pra mim foi uma luz no meio do tunel e estou gostando bastante do resultado.

[felipefialho]

Puts @akfzambrana, quando descubro uma ferramenta e me sinto confortável com ela vem alguém e indica uma melhor, hahaha

[akfzambrana]

@lfeh o MDCSS é fodão, tanto é q esses caras usaram ele como base kkk agora é mais facil pra vc adotar o sc5 😄

[kandebonfim]

Pra quem usa ITCSS tem o itcsscli que tem um comando de documentação (itcss doc).

Eu criei pra mim mesmo e uso nos meus projetos.

O doc tem essa aparência:

[bernardodiasc]

muito bom @kandebonfim!

ITCSS + BEM ftw! :D

[bernardodiasc]

To implementando o https://github.com/sapegin/react-styleguidist num projeto aqui, valeu pela dica @diessica, muito pratico esse trem! :D

[diessica]

@bernardodiasc de nada!

É realmente muito prático. Se o componente é puro (facilita adicionar um live example) e suas proptypes estão definidas e comentadas, a documentação final do componente fica excelente!

Tenho um componente chamadoLoader em um projeto. A documentação dele ficou assim:

As proptypes do componente, que são listadas no style guide pelo próprio react-styleguidist:

Loader.propTypes = {
  size: PropTypes.oneOf(['small', 'medium']),
  white: PropTypes.bool,
  /**
   * Vertical and horizontal centering.
   */
  centered: PropTypes.bool
};

[k8adev]

Sobre ferramentas, eu uso o markdown styleguide generator.

Não é muito conhecido da galera mas recomendo. A escrita dele é agradável e seu output totalmente configurável.

[felipefialho]

@akfzambrana Estou começando um projeto novo e vou testar o SC5, acabei de ver que tem suporte até pra Jade!

Do carario.

Vou testar e dou meu feedback.

[gabrielmanara]

@lfeh estou usando em um projeto novo aqui no trampo, apanhei um pouquinho no começo mas agora está rolando bem. Recomendo o blog desta moça aqui: http://varya.me/en/posts/

Ela é uma das pessoas que mantem essa ferramenta, tem um post dela ai que ajuda você a integrar o SC5 com js. Realmente é uma ferramenta do carario.

[felipefialho]

@gabrielmanara Tentei colocar com Stylus e não consegui.

Sabe se é possível?

[felipefialho]

@keitoliveira To dando uma olhada nesse também

[gabrielmanara]

@lfeh não é possível, rolou até uma issue sobre isso: SC5/sc5-styleguide#663
Segundo eles é algo que eles pretendem ter.