Documentar como deve-se trabalhar com documentação do projeto

[MarceloCajueiro]

Quem quiser trabalhar com documentação, como deve proceder?

Essa é a pergunta que temos que responder.

O @vinicelms está trabalhando com essa parte no i-educar e poderá ajudar a gente nisso.

Issue vista como necessária aqui: #219

[williamespindola]

@vinicelms quais docs existem hoje?

Vejo duas possíveis documentações:

1. De uso, que descreve como o usuário usa e "vive" dentro da aplicação. Exemplo https://www.mautic.org/docs/en/index.html
2. De dev, que descreve como desenvolvedores instalam, configuram e usam apis caso exista. Exemplo: https://developer.mautic.org/

Extra: A Portabilis pode ter um blog pra notícias de novas features, isto é bom para o marketing. Exemplo: https://www.mautic.org/blog/

[fernandosjp]

@williamespindola e @MarceloCajueiro muito legal! @williamespindola a Portabilis, IFMS e o @vinicelms estão trabalhando para a abertura da documentação que já existe #297. Eles estão usando a ferramenta Docusaurus e vai bem na linha do que você esta sugerindo de ter documentações e blog. Na frente de documentações pensamos em:

i) usuário,
ii) administrador do sistema
iii) desenvolvedores.

O que acham?

[vinicelms]

Fiz um PR de como contribuir com a documentação, já dentro da própria estrutura do site: #357

Nas próximas semanas vamos começar a redesenhar como a documentação será feita. Faremos com o âmbito de personas, sendo definidas 3:

• Administrador: Secretaria de Educação, para administrar e entregar todas as definições para o usuário final
• Usuário: vai operar o sistema em seu cotidiano, tendo figuras como professor e secretário de escola
• Desenvolvedor: conterá todos os detalhes técnicos, como API, documentação, contribuição em código e demais itens, com visão de evoluir o produto final e seu ecossistema.

[farribeiro]

@vinicelms quais docs existem hoje?

@williamespindola Conforme o @vinicelms comentou na #199 (comment) ele está transcrevendo o manual do usuário que se encontra no SPB para o docusaurus, segue o link:

https://portal.softwarepublico.gov.br/social/i-educar/manuais-de-usuario

Enquanto demais documentações é inexistente.

[giustin]

@farribeiro @vinicelms @williamespindola apenas melhorando um pouco a mensagem do @vinicelms, o manual que está sendo utilizado é o da Portabilis mais recente, fornecido aos seus clientes em treinamentos hoje em dia. A versão mencionada é de 2013 e não reflete o produto atual.

Aliás, iremos adaptar informações do Portal para não confundir as pessoas que chegarem até a Comunidade pelo Portal do SPB.

[farribeiro]

Obs: O ultimo participante (UFRJ) tinha linkado para o SPB, acreditando onde se encontrava o código mais recente.

[farribeiro]

Surgiu uma discussão com @vinicelms a respeito de não usar ferramentas correlatas como PHPdocumentator, doxygen ou doctrine e entre outras ... Em favor do movimento ágil

Penso aqui, retirar todas as referências comentadas nos arquivos para estas ferramentas e fazer uma documentação do zero.

Opiniões?

[dyego1912]

Alguma atualização sobre esse projeto?

[edersoares]

@dyego1912 nós temos a documentação existente no repositório https://github.com/portabilis/i-educar-website, não foi criado um manual de contribuição, mas pode se basear no conteúdo já criado para trabalhar com a documentação.

[dyego1912]

Certo! Agradeço! Em qui, 29 de ago de 2019 14:17, Eder Soares <notifications@github.com> escreveu:

…

@dyego1912 <https://github.com/dyego1912> nós temos a documentação existente no repositório https://github.com/portabilis/i-educar-website, não foi criado um manual de contribuição, mas pode se basear no conteúdo já criado para trabalhar com a documentação. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#221?email_source=notifications&email_token=AEAFY3NJIMN7W2VMR7ZTE33QHAOC5A5CNFSM4FEH26HKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD5PRBJQ#issuecomment-526323878>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AEAFY3O62KLL7TEGR2Y6SS3QHAOC5ANCNFSM4FEH26HA> .

[edersoares]

Para a documentação ver o repositório https://github.com/portabilis/i-educar-website.