Projektová dokumentace

Měla by obsahovat všechny aspekty, které vývojář potřebuje vědět a které nelze získat přímo od vývojáře. kód. Patří mezi ně zásady a doporučení pro vývoj, úplné pokyny pro nasazení, popisy externí integrace atd. Tento příspěvek vás provede vytvořením výkonného, krásného a čitelného souboru README pro vaši aplikaci. projekt.

Pěkný úvod pro dobře připravenou projektovou dokumentaci najdete na github guides: https://guides.github.com/features/wikis/. Zde se uvádí, že "README by mělo obsahovat pouze nezbytné informace pro vývojáře, aby mohli začít projekt používat a přispívat do něj".

S ohledem na tuto skutečnost si představíme seznam komponent a osvědčených postupů, kterými se ve společnosti Codest řídíme při tvorbě projektové dokumentace.

Rychlý úvod

- Název projektu: toto je nezbytnou součástí každého README.

- Stavové odznaky: pokud používáte externí měření kvality kódu, automatizované testování nebo jiné nástroje, je začátek dokumentu vhodným místem, kde můžete ostatním ukázat, zda fungují.

- Popis: uveďte několik vět o projektu, abyste rychle popsali jeho hlavní účel a co dělá.

Obsah

Seznam obsahu může být užitečný pro dlouhé dokumentační soubory, ale pokud je váš README poměrně stručný, není nutný.

Obecné informace

- O sekci: mělo by se jednat o podrobnější popis projektu - může obsahovat informace o uživatelích, jejich rolích, některých více zapeklitých případech a snímky obrazovky apod.

- Makety: místo pro odkazy na zdroje maket UI/UX, pokud nějaké existují.

• Další informace jako Přístup k serverům nebo Integrace s externími rozhraními API: příklady zahrnují url adresu instance staging, sdílené přístupové údaje, které nejsou citlivé (!), odkazy na dokumentaci, některé pokyny atd.

Instalace

- Požadavky: předběžné podmínky, které musí být splněny před zahájením nastavení aplikace, např. instalace externích nástrojů.

- Nastavení: návod krok za krokem, podle kterého můžete projekt spustit.

- Nastavení: popisují, kde jsou uložena místní nastavení, a poskytují pokyny, jak získat vlastní nastavení.

- Místní konfigurace: pokud existují případy pro místní nastavení, je to dobré místo pro vysvětlení.

Vývoj

Tato sekce je ideálním místem pro instrukce, jako je vývoj funkcí, opravy chyb, hotfixy, společné funkce, testování, průvodce styly, organizace kódu, další vývojové nástroje používané v projektu (např. guardy nebo dockery) atd. Nezapomeňte zmínit všechna pravidla, která každý tým člen by měl vědět.

Nasazení

Poskytněte jasné pokyny krok za krokem pro každé prostředí a vše, co je "dobré vědět" při nasazení.

Další nápady na samostatné sekce

- Dokumentace API

- Seznam změn

- Externí zdroje: místo pro všechny druhy odkazů, které mohou být užitečné.

- Zásobník aplikací: seznam zásobníku aplikací, které v projektu používáme - může obsahovat krátký popis a název poskytovatele.

Tým

Je sporné, zda je nutné zobrazovat aktuální členy projektového týmu (github ve výchozím nastavení poskytuje úplný seznam přispěvatelů), ale vždy je příjemné, když vidíte své jméno jako jednoho z autorů projektu. Pokud tak činíte, udržujte jej co nejaktuálnější.

Několik slov na závěr

Nezapomeňte, že každý projekt je jedinečný a stejně tak i jeho dokumentace. Neexistuje jedno skvělé řešení pro psaní README. Stačí se řídit obecnými radami a nejdůležitější je vždy pamatovat na refaktoring, který se k README také váže. Vždy je dobré podívat se na dokument jako na celek a přehodnotit ho, pokud je třeba něco zobrazit jinak.

Ještě jedna věc: "pokyny" jsou klíčové, takže je pište hodně. Děkuji!

Přečtěte si více:

• Princip "otevřeno-uzavřeno". Musím ho někdy použít?
• Jak napsat dobrý a kvalitní kód?
• Vuelendar. Nový projekt Codestu založený na Vue.js