Wstęp
Nawet najlepszy projekt bez dobrej dokumentacji raczej nie odniesie sukcesu. Dlatego już od początku developmentu warto zadbać o co najmniej szczątkowy plik README. Jest to niejako nieformalna dokumentacja utworzonego projektu. Jest to też 'wizytówka’, która może skutecznie ozdabiać repozytorium na GH. Zgodnie z powiedzeniem „jak nas widzą, tak nas piszą”, skupimy się na najlepszych praktykach tworzenia omawianego pliku. Przedstawię Ci krok po kroku, jak zbudować dobrze prezentujący się opis projektu – tak, aby potencjalny pracodawca, czy inni programiści przeglądający Twój kod, wiedzieli, że mają do czynienia z profesjonalistą.
Dodawanie README do projektu
Podczas tworzenia nowego repozytorium, GitHub automatycznie zaproponuje nam dodanie pliku README.md do projektu. Plik ten możemy również dodać z poziomu lokalnego projektu – wystarczy że wewnątrz niego utworzymy nowy plik o nazwie README.md (zwróć uwagę, że nazwa pliku jest uppercase, istotne jest również rozszerzenie pliku czyli .md).
Co powinno się znaleźć w pliku README?
Aby nasze README było czytelne, warto przy jego tworzeniu zacząć od spisu treści. Na samej górze pliku powinien się znaleźć nagłówek „Table of contents” (o wielkości h1 lub h2), a pod nim wybór konkretnych sekcji:
Sekcjami tymi może być:
– General info (ogólne informację o projekcie)
– Technologies (informację o technologiach jakich użyliśmy w projekcie; rekruterzy często
sprawdzają właśnie tą sekcję)
– Setup (zwięzła instrukcja, w jaki sposób uruchomić program)
– More detailed information about modules (sekcja opcjonalna ale również warta dodania; możemy w niej umieścić informacje o pojedynczych modułach aplikacji)
– Application view (ta sekcja zawiera pliki graficzne przedstawiające wygląd/działanie utworzonej aplikacji)
Jak utworzyć taki spis treści?
W pierwszej kolejności przejdźmy do pliku README.md (ja akurat plik ten modyfikuję z poziomu GH).
Uzupełniajac plik contentem, będziemy bazowali na sekcji Edit file (1).
Zacznijmy więc od samego nagłówka pliku, np. Content of Project. Jego wielkość będzie odpowiadała znacznikowi h1 lub h2. Aby to zrealizować, musimy poprzedzić napis „Content of Project” pojedynczym znakiem „#” – dla nagłówka o wielkości h1 – lub podwójnym „##” – gdy oczekujemy mniejszego napisu (h2).
Skupiając się już na samej zawartości tworzonego spisu treści, musimy zadbać o to, aby kolejno dodawane sekcje były „klikalne”, tzn. aby mogły przenosić użytkownika do odpowiedniego miejsca w pliku README. Tak jak zostało już wspomniane – w spisie treści zadbamy o: General info, Technologies, Setup, More detailed information about module, Application view.
Elementy te będziemy dodawać zgodnie z poniższym wzorcem:
* [General info])(#general-info)
* [Technologies](#technologies)
* [Setup](#setup)
* [More detailed information about modules](#more-detailed-information-about-modules)
* [Application view](#application-view)
Po umieszczeniu powyższego kodu w edytorze, spis treści będzie prezentował się następująco:
Zauważ jednak, że sekcje te nie są klikalne. To dlatego, że musimy w tworzonym pliku umieścić jeszcze tekst, do którego takie odnośniki będą prowadziły.
Najpierw stworzymy akapit „General info”.
Podczas tworzenia nowych sekcji proponuje skorzystać z nagłówków o wielkości (h2, h3) jeśli chodzi o tytuł, natomiast samą zawartość możemy umieścić pomiędzy znacznikami akapitu (<p></p>) lub skorzystać z nieco bardziej seksownej 🙂 formy:
## General info
<details>
<summary>Click here to see general information about <b>Project</b>!</summary>
<b>Lorem ipsum</b>. Lorem ipsumLorem ipsumLorem ipsumLorem ipsumLorem
ipsumLorem ipsumLorem ipsumLorem ipsumLorem ipsumLorem ipsumLorem ipsumLorem
</details>
Już wyjaśniam, o co chodzi z zastosowanymi powyżej tagami <details> oraz <summary>. Dzięki nim, zamiast zwykłego akapitu, otrzymaliśmy „ukrywany” opis naszego projektu. Przy napisie „Click here to see general information…” pojawi się strzałka, która podpowiada użytkownikowi, aby kliknął właśnie w ten napis. Gdy użytkownik tego dokona, pojawi mu się zawartość naszej sekcji, tzn. „General info”. Tak prosta funkcjonalność może zmienić „ścianę tekstu” w interaktywny obszar.
W tym momencie otrzymamy następujący efekt:
Jak jeszcze ozdobić tekst?
Na uwagę też zasługuje tag (<b></b>). Pogrubia on nasz napis, tak samo jak alternatywne rozwiązania:
**Ten tekst będzie pogrubiony**
__Ten tekst również__
Ciekawą opcją może być również dodanie efektu przekreślonego tesktu (możemy go użyć w dokumentacji, aby pokazać użytkownikowi końcowemu z jakiego modułu zrezygnowaliśmy). Aby stworzyć przekreślony tekst użyjemy:
~~Tego modułu w wersji końcowej już nie będzie~~
Na uwagę też zasługuje tag (<b></b>). Pogrubia on nasz napis, tak samo jak alternatywne rozwiązania:
**Ten tekst będzie pogrubiony**
__Ten tekst również__
Ciekawą opcją może być również dodanie efektu przekreślonego tesktu (możemy go użyć w dokumentacji, aby pokazać użytkownikowi końcowemu z jakiego modułu zrezygnowaliśmy). Aby stworzyć przekreślony tekst użyjemy:
~~Tego modułu w wersji końcowej już nie będzie~~
Pozostałe sekcje
Wracając do uzupełnienia pozostałych sekcji ze spisu treści – przejdźmy do Technologies.
Podczas wypisywania stacku technologicznego warto użyć tagów listy nieuporządkowanej (stworzy nam to ładne kropeczki przy każdej technologii). Jak zaimplementować nieuporządkowaną listę?
Tak naprawdę tak samo jak w czystym HTML’u, czyli:
## Technologies
<ul>
<li>One</li>
<li>Two</li>
<li>Three</li>
</ul>
Dygresja
Warto zadbać o dodanie omawianej sekcji związanej z technologiami. To dlatego, że może ona mocno zwiększyć nasze szanse na wyróżnienia się z grona innych programistów (potencjalny rekruter przeglądający nasze projekty będzie od razu wiedział, z jakimi technologiami pracowaliśmy i czy jesteśmy godnymi uwagi kandydatami).
Sekcja Setup i More detailed information about modules
W sekcjach tych opisujemy wszystkie istotne aspekty z perspektywy instalacji projektu oraz ewentualnej obsługi wykorzystywanych modułów. Z racji, że w sekcjach tych nierzadko będziemy chcieli umieścić kod lub polecenie, to warto skorzystać ze znacznika commandline:
```commandline
Komendy w tym znaczniku zostaną podświetlone i sformatowane
```
A tak może wyglądać jednolinijkowy kod Pythona:
```python lambda n: n if n <= 1 else fib(n – 1) + fib(n - 2)```
Przykładowa zawartości sekcji Setup:
## Setup
Get a free API Key at https://example.com <br/>
Clone the repo
```git clone https://github.com/your_username_/Project-Name.git```
Install NPM packages ```npm install```<br/>
Enter your API in config.js ```const API_KEY = 'ENTER YOUR API';```
Application View i dodawanie plików graficznych
Na przykładzie ostatniej sekcji – Application View, zaprezentuję Ci, jak umieszczać pliki w formacie .jpg/.png/.gif etc., które mogą ciekawie zaprezentować działanie naszej aplikacji. Serwis Github niestety nie pozwala nam na dodanie zdjęcia bezpośrednio do pliku README. Dlatego aby tak upiększyć naszą wizytówką projektu, musimy w repozytorium przejść do zakładki „Issues” i tam kliknąć w przycisk „New Issue”.
Następnie upuścimy zdjęcie z naszego dysku na obszar pola służącego do opisywania problemu. Utworzy nam się link który możemy przekopiować do pliku README.
Adres URL (screenshot poniżej) kopiuję i umieszczam w pliku README w sekcji <img>, np. <img src=”URL” width=”50%” height=”50%”>
Rezultat końcowy edytora
Wizualny rezultat końcowy
Pozostałe wskazówki
Na zakończenie, poniżej umieszczam pozostałe wskazówki, o których należy pamiętać, chcąc stworzyć przykuwające wzrok README. Zapamiętaj zebrane w tym artykule hinty i way-of-working, a Twoje Githubowe projekty staną się o wiele bardziej profesjonalne!
Zasada 1.
README pisz tylko w języku angielskim.
Zasada 2.
Pamiętaj o umieszczeniu odnośników do zewnętrznych źródeł (np. wykorzystanego kodu innych programistów) w swoim projekcie.
## Sources
This app is inspired by Devs-Mentoring.pl
Zasada 3.
Na końcu pliku README, możesz umieścić do siebie informacje kontaktowe, np. adres mailowy.
Zasada 4.
Jeżeli nie chcesz ręcznie formatować README, możesz skorzystać z gotowej templaty, np. kliknij tutaj! lub bardziej złożonej kliknij tutaj!
Zasada 5.
Chcąc wygodnie zmieniać rozmiar nagłówka, skorzystaj z poniższego schematu:
# header H1
## header H2
### header H3
#### header H4
##### header H5
###### header H6
