Wskazówki dotyczące niesamowitego pliku readme (i dlaczego jest to ważne)
my, programiści, jesteśmy bardzo dobrzy z kodem i wszystkimi szczegółami naszych projektów. Ale niektórzy z nas (w tym ja) nie mają umiejętności miękkich nawet w społeczności internetowej.,
programista poświęciłby godzinę na dostosowanie wypełnienia i marginesu pojedynczego przycisku. Ale nie poświęciłby 15 minut na plik Readme z opisem projektu.
mam nadzieję, że większość z Was już wie, co readme.md plik jest i do czego jest używany. Ale dla początkujących postaram się wyjaśnić, co to dokładnie jest.
Co to jest Readme.md?
README (jak sama nazwa wskazuje: „read me”) jest pierwszym plikiem, który należy przeczytać podczas uruchamiania nowego projektu., To zestaw przydatnych informacji o projekcie i swego rodzaju podręcznik. Jest to pierwszy plik Github lub jakakolwiek witryna hostingowa Git pokaże się, gdy ktoś otworzy twoje repozytorium..
jak widać tutaj Readme.md plik znajduje się w katalogu głównym repozytorium i jest automatycznie wyświetlany przez github pod katalogiem projektu.
a rozszerzenie.mdpochodzi od słowa: markdown., Jest to język znaczników do formatowania tekstu. Podobnie jak HTML jest to język znaczników, który sprawia, że nasze dokumenty są reprezentacyjne.
oto przykład pliku markdown i jego renderowania na GitHubie. Używam VSCode tutaj do podglądu, który pokazuje podgląd plików markdown jednocześnie.
oto oficjalna ściąga GitHub dla formatu Markdown, jeśli chcesz zagłębić się w język.
teraz porozmawiajmy o interesach., Spędziłeś godziny nad projektem, opublikowałeś go na Githubie i chcesz ludzi / rekruterów/kolegów / (Ex?) Zobacz swój projekt. Czy naprawdę myślisz, że wejdą do root/src/app/main.js, aby zobaczyć Twoją piękną logikę? Poważnie?
skoro już zwróciłem waszą uwagę, zobaczmy, jak sobie z tym poradzić.
generowanie dokumentacji Dla komponentów
oprócz readme projektu, dokumentowanie komponentów ma kluczowe znaczenie dla zrozumiałej bazy kodowej. Znacznie ułatwia to ponowne użycie komponentów i utrzymanie kodu., Użyj narzędzi takich jak Bit (Github) do automatycznego generowania dokumentacji Dla komponentów współdzielonych na bit.dev
Opisz swój projekt! (TL; DR)
napisz dobry opis swoich projektów. Tylko dla wytycznych, możesz sformatować swój opis na następujące tematy:-
- Title (obrazek tytułowy też, jeśli to możliwe…edytuj je na canva.,com jeśli nie jesteś grafikiem.)
- opis(Opisuj za pomocą słów i obrazów)
- Demo (obrazy, linki wideo, linki Demo na żywo)
- zastosowane technologie
- specjalne Gotcha twoich projektów (problemy, które napotkałeś, unikalne elementy Twojego projektu)
- opis techniczny twojego projektu jak – instalacja, konfiguracja, jak przyczynić się.
zagłębimy się w szczegóły techniczne
użyję tego jednego mojego projektu jako odniesienia, który moim zdaniem ma jeden z najpiękniejszych plików readme, jakie napisałem, a nawet natknąłem się na niego., Możesz sprawdzić kod z Readme.md plik tutaj:-
Użyj ikony ołówka, aby wyświetlić kod znacznika :-
Dodaj zdjęcia! Proszę!
możesz mieć fotograficzną pamięć, ale twoi czytelnicy mogą potrzebować prawdziwych zdjęć demo twojego projektu.
na przykład zrobiłem projekt pasjansa i dodałem zdjęcia jako opis w readme.,
Now you may want to add a video description of your projects too. Just like I did. BUT… Github doesn’t let you add a video to the readme… So… So what?
…WE USE GIFS
gify należą do kategorii obrazów, a github pozwala Ci je mieć na readme.
Odznaka Honorowa
odznaki na Twoim readme dają widzowi poczucie autentyczności., Możesz uzyskać niestandardowe/regularnie używane tarcze(odznaki) dla swojego repozytorium z:- https://shields.io
Możesz również uzyskać spersonalizowane tarcze, takie jak Liczba gwiazdek na repo i wskaźniki procentowe kodu.
Dodaj Demo na żywo
Jeśli to możliwe, uzyskaj hosting swojego projektu i skonfiguruj uruchomione demo. Po tym LINK to DEMO do README., Nie masz pojęcia, ile osób może skończyć bawiąc się Twoimi projektami. A rekruter po prostu kocha projekty na żywo. Pokazuje, że Twoje projekty nie są tylko zrzutem kodu leżącym na GitHubie i naprawdę masz na myśli biznes.
możesz użyć hiperłączy w readme. Więc daj link Demo na żywo tuż pod obrazem tytułowym.
użyj formatowania kodu
Markdown daje możliwość sformatowania tekstu jako kodu., Więc nie pisz kodu jako zwykłego tekstu zamiast tego użyj ' (tyldy), aby zawinąć kod wewnątrz formatowania kodu jako takiego- var a = 1;
Github daje również możliwość określenia języka, w którym kod jest napisany, aby mógł używać podświetlenia tekstu, aby uczynić kod bardziej czytelnym. Aby to zrobić, użyj
„{language-extension}<spacja> {Code block Inside}„
{ ` ` } – Triple tilde jest używany do kodu wielowierszowego i pozwala również określić język bloku kodu.,
With Language Highlighting:-
Without Langage Highlighting:-
Use of HTML
Yes, you can use HTML inside. Not all the features though. But most of it., Chociaż powinieneś trzymać się tylko markdown, ale niektóre funkcje, takie jak centrowanie obrazów i tekstu w readme, są możliwe tylko przez HTML.
Dodaj komentarz