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 artifact o
Leia mais

Como utilizar a LZMA SDK (7Zip)

Imagem
Como utilizar a LZMA em C para encapsular as chamadas ao 7Zip em minha aplicação. Primeiramente o que é a LZMA SDK? LZMA SDK é o kit de desenvolvimento que prove documentação, exemplos, interfaces, bibliotecas e ferramentas para o uso do algoritmo de compactação LZMA em aplicações customizadas. Quais são os suportes da LZMA SDK? O SDK dá suporte para as seguinte linguagens C, C++, C# e Java. [ + ] Licença Como o próprio site diz, " LZMA SDK  is placed in the  public domain. " e vai mais alem " 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. " Sendo assim pode ficar tranquilo para utilizar a biblioteca tanto comercialmente como não comercialmente, pois não existem restrições. Ambiente de desenvolvimento Vou utilizar o Microsoft Visual Studio 2010 e SDK baixada diretamente d
Leia mais