Jakie informacje powinny znajdować się w github README.md?

10

Jakich informacji spodziewałbyś się zobaczyć w github README?

Czy wszystko powinno iść w CZYTELNIKU? to znaczy

  • Wprowadzenie

  • Instalacja

  • Wersje

  • Podręcznik użytkownika

  • Realizacja

  • Testowanie

  • Powiązane zasoby

A może powinieneś po prostu umieścić pewne rzeczy w README (wprowadzenie, instalacja, wersje), a inne informacje najlepiej umieścić na wiki Github?

documentation github użytkownik86834
źródło
Umieściłbym także warunki licencji
py_script
Ogólnie rzecz biorąc, powinna istnieć wystarczająca ilość informacji, aby powiedzieć mi, czy projekt jest dla mnie przydatny, jeśli wszystko, co o nim wiem, to nazwa. Nie zakładaj niczego o tym, jak czytelnik to znalazł.
Keith Thompson
1
To pytanie ma bardzo szczegółową / dobrą odpowiedź tutaj: stackoverflow.com/questions/2304863/how-to-write-a-good-readme
Rodrigo Graça

Odpowiedzi:

7

Oczekuję wprowadzenia i krótkiego przeglądu. Powinno być coś, co przekonałoby mnie, że projekt rozwiązuje konkretny problem. Po przeczytaniu pliku README powinienem znać wystarczającą ilość informacji, aby wiedzieć, co robi projekt, czego wymaga, jak go zbudować i jak z niego korzystać. Nie wszystkie informacje muszą znajdować się w pliku README, ale powinny znajdować się linki do tych informacji.

Bryan Oakley
źródło
1
+1 w skrócie. Nie mów „README”, a następnie włóż do niego garść śmieci, których nie trzeba czytać.
Korey Hinton