The latest articles on DEV Community by Highsoft Sistemas (@highsoftsistemas). https://dev.to/highsoftsistemas https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Forganization%2Fprofile_image%2F6375%2F36d3d27e-1d99-4cf7-b5f8-73185c19a279.png https://dev.to/highsoftsistemas en Vinicius Blazius Goulart Thu, 01 Dec 2022 20:41:27 +0000 https://dev.to/highsoftsistemas/como-escrever-boas-documentacoes-na-empresa-5ane https://dev.to/highsoftsistemas/como-escrever-boas-documentacoes-na-empresa-5ane <p>Estou criando este post baseado no <a href="https://documentation.divio.com/" rel="noopener noreferrer">The documentation system</a>, mas por ele ser um artigo longo resolvi fazer um resumo dele com mais algumas coisas. Mas recomendo que você leia e estude este artigo, ele possui mais conteúdo e casos específicos com explicação e contexto para eles.</p> <h2> Tópicos </h2> <p>Uma boa documentação deve ter 4 tópicos principais:</p> <ul> <li>Explicação: explicação discursiva</li> <li>Referência: descrição seca</li> <li>Tutorial: uma lição</li> <li>Como fazer: uma série de passos</li> </ul> <p><a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fwkose03lxqde4bjke2qq.png" class="article-body-image-wrapper"><img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fwkose03lxqde4bjke2qq.png" alt="Descrição da imagem" width="800" height="294"></a><br> <em>créditos: <a href="https://documentation.divio.com/" rel="noopener noreferrer">The documentation system</a></em></p> <h2> Como fazemos na Highsoft? </h2> <p>Depois de escolher um tópico para escrever e documentar, a primeira coisa a fazer é a <em>referência</em> e a <em>explicação</em>. Primeiro deve-se fazer uma explicação literal do termo, e depois explicar como tal tópico funciona em nosso sistema.</p> <p>Para criar o <em>tutorial</em>, pegamos o tópico em questão e explicamos o procedimento de ponta a ponta, de forma simples, rápida, básica e útil.</p> <p>Devemos complementar então com o <em>como fazer</em>, onde tratamos de assuntos mais específicos e nos aprofundamos nas explicações</p> <p>Adicionamos mais um tópico para possíveis avisos e a explicação deles. Como somos um ERP, é normal dispararmos avisos nas telas para informar o que está acontecendo, e temos um tópico para descrever esses avisos e apontar possíveis problemas que podem ocorrer.</p> <p>Por final, temos isso:</p> <p><a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fhblqr25kqnz0mwqgz0wn.png" class="article-body-image-wrapper"><img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fhblqr25kqnz0mwqgz0wn.png" alt="Image description" width="349" height="489"></a></p> <p>Lembre-se de sempre se colocar no lugar do cliente e tentar entender as possíveis respostas que ele precisa:</p> <ul> <li>como fazer isso?</li> <li>O que é isso?</li> <li>o que eu faço quando...?</li> <li>por quê isso aconteceu?</li> </ul> <p>Se sua documentação tem a resposta para essas perguntas, você tem uma boa documentação. Se não, basta adicioná-lo!</p> aws cloud softwaredevelopment Vinicius Blazius Goulart Thu, 01 Dec 2022 20:41:23 +0000 https://dev.to/highsoftsistemas/how-to-write-good-company-docs-i70 https://dev.to/highsoftsistemas/how-to-write-good-company-docs-i70 <p>I'm creating this post based in <a href="https://documentation.divio.com/" rel="noopener noreferrer">The documentation system</a> but since it is a long article I decided to create a summary with of it and a few more things. But I recommend you to read and study this article, it has more contents and specific cases with explanation and context for them.</p> <h2> Topics </h2> <p>A good documentation must have 4 main topics: </p> <ul> <li>Explanation: discursive explanation</li> <li>Reference: dry description</li> <li>Tutorial: a lesson</li> <li>How to Guide: a series of steps</li> </ul> <p><a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fwkose03lxqde4bjke2qq.png" class="article-body-image-wrapper"><img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fwkose03lxqde4bjke2qq.png" alt="Image description" width="800" height="294"></a><br> <em>credits: <a href="https://documentation.divio.com/" rel="noopener noreferrer">The documentation system</a></em></p> <h2> How we starting at Highsoft? </h2> <p>After picking a topic to write and document, the first thing to do is <em>reference</em> and <em>explanation</em>, which we did together. First we take a literal explanation of the term, and after that we explain how such a topic works in our system.</p> <p>To create the <em>tutorial</em>, we took the topic in question and explained the procedure from end to end, in a simple, quick, basic and useful way</p> <p>We must complement then with the <em>how to guide</em>, where we deal with more specific subjects and go deeper in the explanations</p> <p>We added one more thread for possible warnings and the explanation of them. As we are an ERP, it is normal for us to trigger warnings on the screens to inform what is happening, and we have a topic to describe these warnings and point out possible problems that may occur.</p> <p>Finally we have this: </p> <p><a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fldiynzno0onzpn0qidkj.png" class="article-body-image-wrapper"><img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fldiynzno0onzpn0qidkj.png" alt="Image description" width="361" height="481"></a></p> <p>Remember to always put yourself in the customer's shoes and try to understand the possible answers he needs:</p> <ul> <li>how to do this?</li> <li>what is it?</li> <li>what do i do when...?</li> <li>why did this happen?</li> </ul> <p>If your documentation has the answer to these questions, you have a good documentation . If not, just add it!</p> career softwaredevelopment