A importância de um bom arquivo de README

Na correria de um dia de trabalho e com diversos projetos rolando em paralelo, não é difícil se deparar com alguém te pedindo ajuda (suporte) para algo que você desenvolveu a pouco tempo e você até recorda do assunto, porém não fazer a mínima ideia de com utilizar o programa ou utilitário.
Não sei se isso já aconteceu com você, mas comigo acontece bastante. Muitas vezes eu pego algo que desenvolvi ou escrevi e me surpreendo com o que foi feito por mim, as vezes positivamente :D e outras nem tanto!
Cada um se organiza da forma que acredita ser mais produtivo, contudo como eu costumo criar muitas ferramentas para meu uso e acabo compartilhando com outras equipes preciso deixar um documento para consulta rápida no moldes do README [+]  e isso acaba ajudando no processo de resgatar o assunto e mesmo como uma manual de usuário.

Conteúdo para um arquivo README

Ao meu ver um arquivo como esse pode ter tudo o que for necessário para ajudar no desenvolvimento, uso, footprints e até milestones, alguns podem dizer que isso não é nada produtivo e existem muitas ferramentas melhores para realizar essas atividades e eu concordo, mas aqui estamos falando de uma ferramenta pequena e muitas vezes embrionária que precisa ter um escopo mais pragmático de desenvolvimento, dessa forma nada rápido e pratico que um arquivo texto.

Exemplo de seções

  • Cabeçalho
  • Exemplos de uso
  • Versões
  • Changelog
  • Necessidades X Soluções adotadas

Links para outros sites com exemplo



Comentários

Postar um comentário

Postagens mais visitadas deste blog

How use the LZMA SDK (7Zip)

Imagem
How extend the LZMA with C/C++ and implement customized softwares using the 7Zip library. First of all, what is LZMA SDK? LZMA SDK is a package with all you need to extend and developing your own application without recreate the wheel! It is complete with documentation, samples, interfaces, libraries and tools to help in the use of compaction  algorithm LZMA in custom applications. What languages are supported by the LZMA SDK? The SDK supports the following languages C, C++, C# and Java. [ + ] Licence How the own site said, " LZMA SDK  is placed in the  public domain. " and goes beyond " Anyone is free to copy, modify, publish, use, compile, sell, or distribute the original LZMA SDK code, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means. " I understand, that you can use library for commercial or non commercial purpose, without restrictions. Enviroment of development I will use ...
Leia mais

How config Maven to work with NTLM proxy

I have been worked with Maven [+] some time and I can to affirm that is one the best tools to the management of software projects and comprehension, incredibly powerfull, versatile, but far from unanimous among developers. I like to show that is a personal opinion and I respect all other points of view. This post was born from the necessity of install Maven on my developer environment, that has a kind of proxy (NTLM), because until then I saw situations where only was necessary configure the settings.xml file, like described on Maven documentation  (Maven configurando proxy) . Error Message The error message below was constantly displayed when I tried to run the mvn clean install command in the project: C:Dev\MavenTest> mvn clean install [ERROR] Plugin org.apache.maven.plugins:maven-clean-plugin:2.4.1 or one of its dependencies could not be resolved: Failed to read artifa escriptor for org.apache.maven.plugins:maven-clean-plugin:jar:2.4.1: Could not transfer artifa...
Leia mais

ATM Pin encryption using 3DES

Introduction Most modern ATM’s use a Triple Des algorithm to encrypt the pin and send it to a host server for processing. Once the host system receives the pin, it does a translation of the pin from one encryption key to another, and sends it to a bank. In this post I will attempt to explain the process and how it is done in the real world. Overview of the Triple Data Encryption Standard What we all call Triple DES is EDE (encrypt, decrypt, encrypt). The way that it works is that you take three 56-bit keys, and encrypt with K1, decrypt with K2 and encrypt with K3. There are two-key and three-key versions. Think of the two-key version as merely one where K1=K3. Note that if K1=K2=K3, then Triple DES is really Single DES. Triple DES was created back when DES was getting a bit weaker than people were comfortable with. As a result, they wanted an easy way to get more strength. In a system dependent on DES, making a composite function out of multiple DESes is likely to be easier th...
Leia mais