Jak przygotować dobry plik README.md?

Plik opisujący zawartość repozytorium, cel projektu oraz wykorzystane technologie

Jednym z dobrych nawyków przy tworzeniu projektu jest przygotowanie pliku README.md. W pliku tym powinny się znaleźć takie informacje jak krótki opis oraz cel projektu, wykorzystane technologie, wersje języka (PHP5, PHP7, itd.), biblioteki czy frameworki, z których korzystasz. W przyszłości może się okazać, że niektóre wersje zostały zmienione co spowoduje problem z uruchomieniem projektu. Informacje o wersji zawarte w pliku README.md pozwolą szybko znaleźć przyczynę problemu.

 

Co to jest plik README.md

 

Plik README.md jest zbiorem przydatnych informacji na temat projektu, a także swego rodzaju instrukcją. Plik ten jest przechowywany w głównym folderze repozytorium projektu i powinien być pierwszym czytanym plikiem przy otwieraniu nowego projektu. Tworząc własny projekt korzystamy z bibliotek udostępnionych przez innych programistów jako kod open source, które są dla nas przydatne oraz oferują rozwiązania dobrej jakości. Ale czy te biblioteki byłyby używane, jeśli zabrakłoby w nich przyjaznego opisu? Dobry plik README.md służy po to, aby inni programiści mogli w pełni zrozumieć co zawiera nasz kod oraz sprawdzić jakie oferuje rozwiązania. Nawet jeśli dany kod nie będzie udostępniony publicznie to warto stworzyć plik README.md dla siebie, dzięki temu jak w przyszłości trzeba będzie do niego wrócić, to w jednym miejscu będzie można sobie szybko przypomnieć co dany kod robi.

 

Elementy, które powinien zawierać plik README.me

 

Główne elementy, które zawsze powinny znaleźć się w pliku to:

  1. Wprowadzenie – cel projektu – jest to streszczenie projektu, powinno być nie za długie i w ciekawy sposób opisywać co jest celem projektu oraz jakie problemy rozwiązuje.
  2. Technologie – ten element powinien zawierać użyte języki, biblioteki oraz ich wersje.
  3. Instalacja i uruchomienie – opis w jaki sposób zainstalować bibliotekę w swoim projekcie oraz jak ją uruchomić. Należy tutaj również podać minimalne wymagania sprzętowe.

 

Warto również zamieścić następujące elementy:

 

  • Spis treści – przyda się w sytuacji, gdy dokumentacja projektu jest dość obszerna.
  • Zakres funkcjonalności – zestawienie głównych funkcji projektu.
  • Przykłady użycia – jest to zazwyczaj jako fragmenty kodu zaprezentowanie w jaki sposób korzystać z biblioteki.

 

Ogólnie plik README.md powinien być czytelny, staranna dokumentacja sprawia, że nasze repozytorium prezentuje się dobrze w oczach innych programistów.

 

Autor: Dawid Kwiatkowski


Opublikowano:

Mentax na Facebook'u