Jak napisać dobre README projektu na GitHubie?

O dobrych nawykach, w tym o dodawaniu pliku READEME.md, wspomniałam już wcześniej przy okazji wpisu o tworzeniu repozytrium na GitHubie (co to jest i jak stworzyć znajdziesz we wpisie Git i Github od podstaw). Jeśli do niego nie zaglądaliście to tylko przypomnę – plik README warto, a nawet należy dodawać w każdym nowym projekcie. Dziś będzie trochę o tym jak taki plik napisać dobrze, kilka przykładów oraz szablon do wykorzystania w waszych projektach.

Co to jest plik README?

README – jak sama nazwa wskazuje plik: „przeczytaj mnie” jest pierwszym plikiem, który powinno się czytać otwierając nowy projekt. To zbiór przydatnych informacji o projekcie, a także swego rodzaju instrukcja. Plik tekstowy README pojawia się w wielu różnych miejscach i nie tylko dotyczy programowania, choć dzisiaj o takich przypadkach będzie mowa.

README.md dla rails bootstrap

przykład README dla gemu Bootstrap (Ruby On Rails)

Dodany plik README na GitHubie pojawia się pod listą plików w repozytorium.

Ucząc się programowania czy pracując zawodowo nie raz trafiamy i korzystamy z publicznych repozytorów. Używamy bibliotek udostępnionych przez innych developerów jako kod open source czy dorzucamy swoją cegiełkę dla dobra wspólnego, kontrybuując projekt (zgłaszając błędy – bugi, naprawiając błędy, dodając nowe funkcjonalności). Zapewne korzystamy z tych projektów, bo akurat są dla nas przydatne i oferują rozwiązanie dobrej jakości. Ale czy byłyby używane, gdyby zabrakło w nich przyjaznego opisu – dobrego README?

Gwarantuję, że poznacie jeszcze uczucie rozczarowania, gdy znajdziecie potencjalne rozwiązanie swoich wszystkich problemów w bibliotece czy projektcie, którego opis jest słaby, bezużyteczny, albo zupełnie go nie ma.

Po co pisać dobre README?

Pewnie już się domyślacie – dobre README jest po to, aby inni mogli zrozumieć co zawiera wasz kod i dlaczego jest warty uwagi. Plik README jest też niezbędny, by projekt dało się wyszukać – na GitHubie, ale też w wyszukiwarkach np. Google.

Dopiero się uczę, dlaczego mam się martwić dodawaniem pliku REAME? Przecież ten kod jest tylko dla mnie, a nie dla całej społeczności.

Wątpię, że kod jest tylko dla Ciebie…. a mimo to README warto dodać 😉

README dla Juniora

Okey, czas na kilka powodów, dla których należy dbać o README od pierwszego projektu!

Nawet jeśli kod „jest tylko dla Ciebie”, to możliwe, że za jakiś czas do tego kodu wrócisz. Dobre README pozwoli ponownie uruchomić projekt, bez tracenia czasu na przypominanie sobie „co to właściwie było?”.

GitHub to wizytówka początkującego programisty. Projekty na GitHubie to najczęściej nasze portfolio. W momencie, gdy nie mamy liczącego się doświadczenia komercyjnego, atrakcyjnych projektów non-profit, jedynym z najlepszych sposobów pokazania się rekruterom jest zaprezentowania tego co się do tej pory zrobiło w formie repozytoriów. Najlepiej poprzez przygotowanie kilku pokazowych projektów, którymi chętnie pochwalimy się na rozmowie o pracę.

Jeśli się dopiero uczymy i wrzucamy ćwiczeniowe projekty warto je dobrze opisywać. Dzięki temu nawet nietechniczny rekruter będzie wstanie przeczytać z jakimi technologiami się spotkaliśmy i czy pasuje to do profilu kandydata jakiego szuka.

Po polsku czy po angielsku?

Oczywiście, po angielsku. Mimo, że projekt sam w sobie jest po polsku, to opis projektu dodawaj po angielsku. Wyjątkiem będą projekty na uczelnie, gdzie często w wymogach trzeba prowadzić dokumentacje w języku polskim. W każdym innym wypadku opisuj swoje projekty w języku angielskim.

README.md … chwila, o co chodzi z tym .md?

Rozszerzenie .md pochodzi od słowa markdown. To język znaczników służący do formatowania tekstu. Może na początku nie będzie to dla was oczywiste, ale markdown powstał w celu uproszczenia tworzenia tekstu. Tak jak w języku HTML nagłówek najważniejszy (pierwszego rzędu) umieszamy w znaczniku h1, tak w naszym dokumencie umieścimy przed nagłówkiem znak #.

Pliki .md edytujemy w dowolnym edytorze tekstowym czy edytorze kodu (notatnik, sublime, atom, VS… etc).

Więcej o tym jak używać markdown znajduje się w ściądze od GitHuba.

Edytor z podglądem znajdziecie na dillinger.io

Jak napisać dobre README – poradnik dla zielonych 😉

README - junior developer

W nowym projekcie utwórz plik README.md.

Upewnij się, że plik ten zawsze zawiera następujące elementy:

  • Tytuł i śródtytuły
  • Wprowadzenie – cel projektu
  • Technologie
  • Uruchomienie

Rozważ też dodanie elementów takich jak:

  • Spis treści
  • Ilustracje
  • Zakres funkcjonalności
  • Przykłady użycia
  • Status projektu
  • Źródła
  • Inne informacje

Aż tyle? Przecież ja nie mam tyle do powiedzenia o swoim projekcie!

Masz, tylko jeszcze tego nie wiesz 😉

Tytuł i śródtytuły

Tytuł powinen jasno mówić z czym mamy doczynienia. Zazwyczaj tytuł, to nazwa projektu jako nagłówek typu H1, poprzedzony znakiem #. Jeśli nazwa projektu nie zdradza jego zawartości warto w tytule jednak zasugerować czego dotyczy.

readme - tytuł projektu

Dodatkowo w tekście powinny się znajdować tytuły sekcji oraz w razie potrzeby śródtytuły. Zapisujemy je analogicznie do każdego innego dokumentu, tak, aby README było czytelne. W pliku README.md nagłówki zapisuje się się za pomocą wielokrotności znaku #:

# nagłówek H1
## nagłówek H2
### nagłówek H3
#### nagłówek H4
##### nagłówek H5
###### nagłówek H6

Wprowadzenie

Wprowadzenie albo bardziej streszczenie. Powinno być nie za długie (nie chcemy czytać eseju na temat projektu). Ważne by w ciekawy sposób przedstawić: co jest celem projektu? jaki problem rozwiązuje dana aplikacja? W małych projektach 2-3 zdania wystarczą.

Jeżeli jest to nasza ćwiczeniowa aplikacja warto zapisać motywację do stworzenia akurat takiego projektu np. żeby nauczyć się konkretnej technologii. Projekt powstał w ramach hackatonu? Na potrzeby organizacji non-profit? Jest to aplikacja utrwalająca zakres materiału z warsztatów albo kursu online? Zdecydowanie warto o tym tu wspomnieć.

Technologie

Wypisujemy użyte języki, biblioteki i ich wersje.

Na przykład:

  • Bootstrap 3 czy 4
  • AngularJS 1.6 / Angular 2+/4/5/6
  • PHP 5 czy 7
  • Python 2.7 czy 3.6
  • Rails 4 czy 5

itd…

Dlaczego?
Po pierwsze pozwoli to w przyszłości uruchomić projekt – wersje bibliotek zmieniają się w czasie, później niepozorna zmiana może sprawić wiele problemów. Dobrze znać wersję jaka była użyta, gdy nasz kod dział dokładnie tak jak się spodziewaliśmy.

Druga sprawa to rekrutacje. Rekruterzy IT przeglądają konta GitHub kandydatów. Nawet jeśli nie mają wiedzy technicznej, aby ocenić jakość rozwiązań, znają słowa klucze związane ze stanowiskami na jakie rekrutują. Opis użytych technologii pomoże wyróżnić się wśród innych kandydatów.

Załóżmy, że na pewien staż aplikuje mnóstwo kandydatów, a czas na rekrutacje jest ograniczony. CV zostały odsiane, zostało dwóch, porównywalnych kandydatów i ostatni termin w kalendarzu. Ich konta GitHub zawierają tyle samo projektów, ale jeden kandydat w każdym projekcie ma podane technologie (część zbieżna z profilem idealnego kandydata), a drugi nie dodaje plików README, albo ma słabo opisane projekty. Jak myślicie, który zostanie zaproszony na rozmowę?

Uruchomienie

Jak uruchomić projekt?
Czy projekt ma minimalne wymagania sprzętowe?

Biblioteki i wersje zostały wymienione w punkcie wyżej. Można te dwa punkty – technologie oraz postawienie/wymagania sprzętowe połączyć w jedno w razie potrzeby.

Przy podziale na dwa podpunkty tutaj warto skupić się konkretnie na instrukcji uruchomienia projektu. Dla strony www / aplikacji to może być instrukcja ustawienia lokalnego środowiska lub link do GitHub pages czy zdeployowanej aplikacji na Heroku. Czy potrzebne są dane wejściowe i jeśli tak, to w jakim formacie.

Inne elementy, które poprawią wasze README:

Spis treści

Przyda się zwłaszcza, jeżeli wasza dokumentacja jest dość obszerna. Spis treści można wykonać jako zwykłą listę z linkami do nagłówków.

GitHub automatycznie dodaje do nagłówków id wg treści wewnątrz znacznika (spacje zostaną zamienione na znak -), dlatego linki są zbudowane w ten sposób: https://github.com/user/repo-name#header-name.
Pozwala to na proste stworzenie spisu treści np:

## Table of contents
* [General info](#general-info)
* [Technologies](#technologies)
* [Setup](#setup)

## General info
This project is simple Lorem ipsum dolor generator.
	
## Technologies
Project is created with:
* Lorem version: 12.3
* Ipsum version: 2.33
* Ament library version: 999
	
## Setup
To run this project, install it locally using npm:

```
$ cd ../lorem
$ npm install
$ npm start
```

A będzie wyglądał tak:

README - spis tresci

Ilustracje

GitHub pozwala na umieszczenie grafik w README. W dokumentacji technicznej nie chodzi o to, by była ładna, tylko czytelna i zrozumiała. Ilustracje nie są konieczne, ale mogą podnieść wartość estetyczną projektu. Możesz wyświetlić np. logo aplikacji, wykresy, schematy, przykładowe screeny. Może chcesz stworzyć ilustrowaną instrukcję obsługi?

Ilustracje w readme

Utwórz folder w swoim repozytorium, dodaj tam obraz. Następnie użyj ścieżki do pliku, aby je prawidłowo wyświetlić za pomocą: ![tekst alternatywny](ścieżka/do/pliku). Możesz używać też obrazów z poza swojego repozytorium, o ile są publicznie dostępne (jednak zawsze istnieje ryzyko, że właściciel zasobów usunie je ze swojej domeny, a wtedy znikną z twojej dokumentacji): ![tekst alternatywny](url grafiki)

Przykład: w moim pliku README chcę umieścić schemat blokowy ilustrujący działanie algorytmu. Plik schema.jpg przechowuję w repozytorium w folderze o nazwie images, aby wyświetlić go w dokumencji umieszczę kod:

![Algorithm schema](./images/schema.jpg)

Zakres funkcjonalności

Nie zawsze jest sens opisywać zakres funkcjonalności. Dla strony wizytówki czy prostej aplikacji typu to-do lista to przerost formy nad treścią.

Z drugiej strony pozornie prosty projekt jak to-do lista można rozbudować o wiele ciekawych opcji, którymi chcemy się pochwalić np. rejestracja użytkowników, zapisywanie i sortowanie zadań według daty, komentowanie zadań czy eksport danych do plików.

README - zakres funkcjonalnosci

Przykłady użycia

W przypadku kodu „wielokrotnego użycia” czy własnej biblioteki niezbędne może być dostarczenie instrukcji użycia naszego projektu, zazwyczaj jako fragmenty kodu.

## Code Examples
To generate lorem ipsum use special shortcode: `put-your-code-here`

powyższy kod wyświetli:
readme - dodanie kodu

Status projektu

Warto dodać informację o statusie projektu, zwłaszcza jeżeli jest w trakcie rozwoju. Jeżeli jest to wasza biblioteka, warto wymienić jakie zmiany są planowane, kierunki rozwoju, albo zaznaczyć, że rozwój został zakończony.

Źródła

To dość popularne pytanie na grupach: czy dodawać informację, jeżeli nasz projekt powstał na podstawie tutorialu, albo został zainspirowany jakimś zadaniem?

Odpowiedź jest prosta: oczywiście, że tak.

## Sources
This app is inspired by Rando Kim book „Time of Your Life”
and Android app tutorial by [@eericon](https://www.eericon.github.io/post/timer-android)

Nie rozumiem wątpliwości w tej kwestii. Nie ma nic wstydliwego w tym, że uczymy się z różnych źródeł i dokumentujemy nasze postępy. W trakcie nauki robimy różne tutoriale, dobieramy materiały do nauki. Rzadko jest tak, by ktoś bezmyślnie kopiował tutorial, zupełnie nic w nim nie zmieniał, niczego się nie nauczył.

Skoro nasz kod powstał na podstawie cudzego kodu, to należy zamieścić o tym informację.

Może być tak, że korzystamy ze starego tutorialu np. piszemy aplikację z tutorialu do Rails 3 i piszemy ją od nowa zgodnie z wersją Rails 5 wykorzystując nowe mechanizmy frameworka. Zdecydowanie warto to zaznaczyć.

źródła nauki - readme

W przypadku, gdy nasz kod został tylko zainspirowany innym rozwiązaniem, inną aplikacją można o tym wspomnieć i wymienić jak się zainspirowaliśmy, jakie zmiany zostały wprowadzone, jakie funkcjonalności rozwinięte.

Gdy rozwiązujemy zbiory zadań, warto dodać gdzie się znajdują opisy ćwiczeń. Jednocześnie, jeżeli po czasie będziemy chcieli wrócić do źródła, łatwo znajdziemy link do odpowiedniej strony.

W ten sposób też honorujemy autora, który podzielił się wiedzą, włożył czas w przygotowanie i udostępnienie materiału.

Inne informacje

Info o autorze, możliwość kontaktu, linki do strony www i mediów społecznościowych, rodzaj licencji na jakiej udostępniacie swój kod czy informacje jak kontrybuuować (rozwijać) projekt – to tylko przykładowe elementy, które można jeszcze umieścić w projekcie.

Dobre, czytelne README

Wszystko powyżej jest moją propozycją. Piszcie tak, by plik README był po prostu czytelny. Staranna dokumentacja sprawia, że wasze repozytorium prezentuje się dobrze w oczach rekruterów, a także innych programistów.

Dobre README można stworzyć na wiele różnych sposobów. Rzućcie okiem na poniższe przykłady:

  • Node-chat – prosty opis, screen aplikacji, przykłady użycia
  • WebApp – świetny przykład opisu strony typu landing page oraz aplikacji wykorzystującej API – opis działanis, screeny, lista technologii jakie zostały użyte w rozwiązaniu, dodatkowo informacja o funkcjonalnościach, które będą zaimplementowane
  • Pomolectron – mamy logo, screeny, instrukcję instalacji oraz opis użycia
  • Git point – przykładowa aplikacja na Androida – spis treści ułatwia nawigację, screeny, wymienione funkcjonalności oraz informacja jak wesprzeć rozwój

Szablon README

Zostawiam wam przykładowy szablon pliku README.md do pobrania. Możecie zobaczyć jak jest sfotmatowany, a następnie przekopiować sobie wersję raw do swojeg pliku README.md szablon README