How a good README file is important

In the rush of a day's work with several projects going on in parallel, it is not hard to come across someone asking you for help (support) for something you developed recently, but hasn't make the slightest idea how use this program or utility currently.

I don't know if it happens with you, but with me it happens much. Many times when I do the review of something I had developed and passed a little time without see, I stay surprised with it, sometimes as a positive surprise and others not so much!
Each one do the organization the way it believed to be more productive, but as I usually create many tools for myself and sometimes I share it with other staff members, so it's necessary leave a document for quick reference in templates README [+] and it ends up helping in the process of rescue the subject and even as a user manual.

The content of a README file

In my point of view, a file as this can have anything what is necessary to help in the development and be a good guide for quick reference with use examples and any kind of warnings and tips, someone can say: It isn't productive and have many other tools to do that in the best way and I agree, but here we talk about a little tool and many times a snapshot with a scope more pragmatic of development, so nothing is more quickly and practice than a text file.

Examples of section

  • Header
  • Examples of use
  • Versions
  • Changelog
  • Scope X Solution

Links to the other sites with examples


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

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