Uwaga! Trwają prace nad nową wersją serwisu. Mogą występować przejściowe problemy z jego funkcjonowaniem. Przepraszam za niedogodności!

🔥 Webinar Q&A na temat IT – pytaj, o co chcesz! już 24.11.2022 (czwartek) o 20:30

Jak ulepszyć README projektu

Wyróżnij się na tle pozostałych kandydatów

Posiadanie README to już coś – ponieważ wielu kandydatów do IT po prostu je pomija – ale jak jeszcze bardziej ułatwić rekruterowi zapoznanie się z naszym projektem i wyróżnić się spośród osób, które jednak postarały się i zamieściły opis na repozytorium? Oto kilka wskazówek.

Spis treści

Jeśli interesują Cię podstawowe zasady tworzenia README projektu, to zapraszam do lektury mojego artykułu „Jak napisać README do projektu na GitHubie”.

 Dodatkowy spis treści

GitHub ma już wbudowany spis treści i generuje go automatycznie z nagłówków. Jest on dostępny w lewym górnym rogu README po kliknięciu w ikonę spisu treści.

wbudowany spis treści na GitHubie

Nie każdy jednak musi o tym wiedzieć i będzie scrollować w poszukiwaniu interesującej go sekcji. Dlaczego mu tego nie ułatwić?

W Markdownie spis treści stworzymy przez podlinkowanie ID danej sekcji. ID znajdziesz w adresie URL po kliknięciu w element wbudowanego na GH spisu treści lub w ikonę linku, która na hover pojawia się przy nagłówku sekcji.

### Contents:

[Installation](#installation)
[Solutions provided in the project](#solutions-provided-in-the-project)
[Conclusions for future projects](#conclusions-for-future-projects)
[Thanks](#thanks)

Możesz podejrzeć działanie tego rozwiązania, kopiując powyższy kod np. do aplikacji stackedit.io/app. Pamiętaj, żeby przed testowaniem dodać odpowiednie sekcje:

### Contents:

[Installation](#installation)
[Solutions provided in the project](#solutions-provided-in-the-project)
[Conclusions for future projects](#conclusions-for-future-projects)
[Thanks](#thanks)

# Installation

# Solutions provided in the project

# Conclusions for future projects

# Thanks

Na końcu tego artykułu linkuję repozytorium, w którym taki spis treści zastosowano. Będzie tam także GIF, więc zapraszam do dalszej lektury.

 GIF prezentujący działanie projektu

Zamieszczenie screena to już coś. Przypominam, że jeśli chcesz wykorzystać własny obraz, powinieneś dodać go do katalogu projektu i podać do niego ścieżkę, np. tak:

![alt text](./assets/screen.png)

Ale własny GIF jest już jak pierwszy poziom wtajemniczenia. Wielokrotnie nasze projekty wymagają instalacji na dysku lokalnym odbiorcy. Jak sądzisz – ilu rekruterów to zrobi? Aby nie tracić ich zainteresowania i wstępnie zapoznać z działaniem projektu, możemy nagrać ekran z działaniem naszej aplikacji, stworzyć z tego GIF-a i zamieścić w projekcie.

Po kolei:

  1. Nagraj ekran, np. z pomocą darmowej wtyczki Awesome Screenshot.
  2. Uzyskane wideo zamień na GIF. Możesz skorzystać z darmowych rozwiązań online, np. cloudconvert.
  3. Dodaj GIF do plików projektu.
  4. Umieść GIF w README. Możesz to zrobić na dwa sposoby:
    1. podobnie jak screen:
      ![alt text](./assets/screen.gif)
    2. a jeśli chcesz mieć wpływ na rozmiar GIF-a, to użyj zapisu:
      <img src="./assets/screen.gif" width="300" height="200" />

 Wideo z omówieniem projektu

Wideo to świetny sposób na zaprezentowanie nie tylko projektu, ale i własnej osoby – tego, w jaki sposób się komunikujemy i czy potrafimy opowiadać o swoim kodzie. Nie każdy dobrze odnajdzie się w takiej formie przekazu, ale jeśli masz ochotę z niej skorzystać, to poniżej podrzucam garść wskazówek.

 Drag & drop

Wideo do 10 MB można zamieścić poprzez przeciągnięcie i upuszczenie go w polu edycji pliku README. Wspierane formaty oraz instrukcję załączania plików znajdziesz w dokumentacji GitHuba.

Bardzo prawdopodobne, że Twoje wideo przekroczy 10 MB. Wówczas – jeśli chcesz pozostać w darmowym planie – pozostaje obejść system i po prostu zamieścić link do wideo np. z YouTube’a (niestety embed nie zadziała). Jak wyróżnić link do wideo?

Według mnie najlepszym sposobem jest zamieszczenie screena filmiku i dodanie do niego linku. Odbiorca dostaje jednoznaczną informację, że ma do czynienia z nagraniem, a po kliknięciu zostaje przekierowany na stronę z wideo.

UWAGA: tym razem nie możemy skorzystać z opcji dodania grafiki (screena) do naszego repozytorium, ponieważ wówczas kliknięcie w nią spowoduje przekierowanie nie do strony z wideo, lecz do pliku z grafiką na naszym repo. Rozwiązaniem jest zamieszczenie screena np. w darmowym serwisie do hostowania grafik.

Wówczas screen i link do filmiku zamieścimy w README w taki sposób:

[![alt text](http://i.imgur.com/image-id.png)](https://youtu.be/TFQBb4r207c "Czas na TypeScript")

 

Jeśli chcesz w swoim README zamieścić badge, statystyki, ciekawe grafiki, to polecam zajrzeć na repozytorium Awesome GitHub Profile README. Co prawda dotyczy ono README profilowych, lecz znajdziesz tam wiele elementów, które równie dobrze możesz wykorzystać w opisie projektu. Na stronie głównej tego repo podejrzysz m.in. zastosowanie spisu treści i GIF-a.

Udostępnij ten artykuł:

Mentoring to efektywna nauka pod okiem doświadczonej osoby, która:

  • przekazuje Ci swoją wiedzę i nadzoruje Twoje postępy w zdobywaniu umiejętności,
  • uczy Cię dobrych praktyk i wyłapuje złe nawyki,
  • wspiera Twój rozwój i zwiększa zaangażowanie w naukę.