Jak stworzyć dobre Readme

Jak stworzyć dobre Readme

Plik Readme jest dokumentem, który czytamy jako pierwszy zapoznając się z nowym projektem/produktem. No, chyba, że interesuje nas faktura 😛 Tworząc nowy projekt już powinniśmy mieć na względzie jak stworzyć dobre Readme. Plik ten pojawia się w wielu miejscach; to podstawowe informacje, przewodnik i zapis myśli programisty.

Jak stworzyć dobre Readme

Dobre Readme zawiera podstawowe informacje przedstawione w sposób czytelny i zrozumiały. Pozwala zrozumieć kod lub ideę działania programu. Jest pierwszym krokiem i źródłem informacji przy pojawieniu się problemu / pytań. A więc, jak stworzyć dobre Readme?

Nie zapominajmy, że pisanie dokumentacji to także część pracy programisty. Nigdy nie możesz być pewny, kto będzie czytał Twój pliku Readme. Załóżmy, że jesteśmy początkującym koderem. Załóżmy, że na GitHubie publikujemy program, z dobrym Readme. Po kilku miesiącach planujemy coś z niego zaczerpnąć (jakiś service, albo moduł) do kolejnego projektu.

„Kurde, przecież działało?!”

Znacie to uczucie, kiedy chcecie komuś pokazać program, a macie repozytoria:

my-first-app, my-first-app-fixed, my-first-app-hello-world, react-asasasas-crud-app, react-asssaa-rest-app…

A gdy w końcu znajdziecie i chcecie je odpalić, coś idzie nie tak? „Kurde, przecież działało?!”. Wystarczyło trochę uporządkować projekty, napisać dobre Readme, z dwiema komendami odpalającymi całą paczkę. Ile to tłumaczenia i nerwów mniej!

Drugim przykładem jest share’ownie kodu źródłowego ze społecznością (tutaj chyba nie warto wchodzić w szczegóły), gdzie na nieopisany kod, program czy repozytorium nikt nawet nie spojrzy.

Trzecim benefitem jest wygląd naszego kodu np. przy rozmowie rekrutacyjnej na wymarzone stanowisko pracy. Skoro dajemy w CV link np. do naszego profilu na GitHubie, zadbajmy, aby nasze repozytoria wyglądały co najmniej dorze.

Jeśli usuniemy bałagan z naszych repo i jak stworzymy dobre Readme, świadczyć to będzie o nawyku pisania dokumentacji, dokładności i naszej rzetelności. Dobre Readme zadziała jak dobre CV, wyróżni nas z tłumu i postawi w dobrym świetle.

Jak stworzyć dobre Readme

  1. Readme zawsze piszemy po angielsku.
  2. Używamy pliku z rozszerzeniem .md (przykład Readme.md). Czasy Readme.txt odeszły do lamusa, dzięki językowi Markdown szybko urozmaicimy treść wizualnie, ułatwiając czytanie i wyszukiwanie treści. Dodatkowo język Markdown jest dużo prostszy i szybszy w tworzeniu dokumentów niż HTML.
  3. Obowiązkowe elementy:
    • Tytuł i podtytuł (Title, Subtitle) – tytuł – wiadomo. A w podtytule maksymalnie dwoma zdaniami opisujemy nasze dzieło. Ma to za zadanie namalować obraz, czym jest nasz stwór 🙂
    • Wprowadzenie (Introduction), tutaj, aby ułatwić sobie życie odpowiedzmy na kilka pytań.
      1. Dlaczego to stworzyliśmy?
      2. Jaki problem rozwiązuje?
      3. Czym i dla kogo zbudowaliśmy?
      4. Czego się nauczyliśmy?
      5. Czym się wyróżnia?
      6. Co robi?
    • Technologie (Techologies): te użyte i wymagane oraz warto zastanowić się:
      1. Dlaczego użyto tych, a nie innych technologii?
      2. Jakie mogą być / są zalety z tym związane?
      3. Jakie mogą być / są problemy z nimi związane?
    • Instrukcje jak uruchomić (Setup / Launch)
    • Typ licencji (Licence), tutaj w wyborze może pomóc https://choosealicense.com/
  4. Elementy uzupełniające
    • Spis treści (Table of Contents)
    • Podgląd funkcjonalności lub wyglądu programu (Demo / Preview), może być nawet w formie animowanych gif’ów
    • Obrazki, zrzuty ekranu (Illustrations / Screenshots)
    • Przedstawienie funkcjonalności (Features / Scope of functionalities)
    • Przykłady różnych zastosowań (Usage / Examples of use)
    • Informacje o statusie projektu (Development / Project status)
    • Źródła z jakich czerpaliśmy (Sources)
    • Informacje uzupełniające (Other information), np odnośniki do wikipedii, czy stron internetowych z informacjami
    • Podziękowania (Contribute / Contributors / Credits), to drobna rzecz, ale warto wspomnieć o tych, dzięki którym projekt gna na przód
    • Pole kontaktowe (Contact)
    • Badges oraz emoji – nie są obowiązkowe, ale często pozwalają w prosty sposób zaprezentować status, lub co się robi. Niewątpliwie urozmaicają wizualnie treść pliku Readme.

Jak widać, nie jest to trudne. Mam nadzieję, że teraz już wiadomo, jak stworzyć dobre Readme.

Please follow and like us:

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Pola, których wypełnienie jest wymagane, są oznaczone symbolem *