Ako pripraviť dokumentáciu k projektu?

Napíšte názov svojho projektu. Prvá vec, ktorú by ste pri písaní README pre svoj projekt mali uviesť, je názov projektu. Spolu s názvom by ste mali uviesť aj číslo najnovšej verzie a dátum jej poslednej aktualizácie.

Napíšte popis svojho projektu. Ďalšia vec, ktorú musíte zahrnúť do svojho súboru README, je stručný popis vášho projektu. Vysvetlite, čo projekt robí, prečo existuje a aké problémy rieši. Môžete tiež zahrnúť akékoľvek špeciálne funkcie, snímky obrazovky, štýl kódu, použitú technológiu alebo rámec alebo čokoľvek iné, čo by mohlo byť užitočné pre používateľov a vývojárov.

Vysvetlite všetky požiadavky, ktoré má váš projekt. Ak váš projekt potrebuje na správnu funkciu špeciálne požiadavky, uveďte tieto požiadavky a pokyny alebo odkaz na pokyny na ich inštaláciu.

Zahrňte ukážku kódu. Uveďte jasný a stručný príklad toho, na čo sa váš projekt používa. Kód by mal byť pre vývojárov ľahko pochopiteľný a API by malo byť jasne viditeľné.

Poskytnite inštalačné pokyny. Vysvetlite používateľom, ako uviesť váš softvér do prevádzky vo formáte krok za krokom. Vaše pokyny by mali byť čo najjasnejšie. Predpokladajme, že vaši používatelia nemajú znalosti o vývoji softvéru alebo správe systému.

Vysvetlite, ako používať softvér. Povedzte ľuďom, ako vyťažiť maximum zo svojho softvéru. Poskytnite podrobné pokyny, ako používať softvér, ako aj rôzne možnosti konfigurácie a ako ich nastaviť.

Informujte používateľov, ako získať technickú pomoc. Poskytuje odkazy na akékoľvek zoznamy adries, kanály IRC alebo komunitné fóra, na ktoré sa môžu používatelia obrátiť o technickú pomoc. Tiež dajte skúsenejším používateľom vedieť, kde môžu odoslať chyby a nápady, aby bol projekt lepší.

• Ak zistíte, že od rôznych používateľov dostávate veľa rovnakých otázok, možno budete chcieť zahrnúť do projektovej dokumentácie často kladené otázky (FAQ).

Vysvetlite, ako prispieť. Ak pracujete na projekte s otvoreným zdrojovým kódom, dajte svojim používateľom vedieť, ako môžu do vášho projektu prispieť. Vysvetlite všetky svoje štandardy a poskytnite niekoľko pokynov potenciálnym prispievateľom.

Vymenujte kredity. Vždy poskytnite kredit tam, kde je splatný. Nezabudnite uviesť mená všetkých prispievateľov a tiež odkazy na knižnice alebo programy tretích strán, ktoré ste použili. Zahrňte odkazy na všetky inšpirácie, ktoré ste mohli mať pri vytváraní projektu.

Uveďte svoje kontaktné informácie. Ľudia vás môžu chcieť kontaktovať z akéhokoľvek dôvodu. Nezabudnite zadať platnú e -mailovú adresu, pomocou ktorej vás môžu ľudia kontaktovať.

• Niektoré krajiny môžu zo zákona vyžadovať dodatočné informácie, ako napríklad poštovú adresu alebo názov spoločnosti.

Zadajte licenčné informácie. Je dôležité, aby používatelia vedeli, ako sa váš projekt licencuje. Na internete je k dispozícii množstvo štandardných licencií, ktoré môžete použiť. Vysvetlite, akú licenciu váš projekt používa, a tiež licencie akýchkoľvek knižníc alebo programov tretích strán, ktoré by ste mohli použiť.

• Vo svojich dokumentáciách nemusíte vysvetľovať celú licenciu. Len dajte používateľom vedieť, akú licenciu váš projekt používa, a poskytnite odkaz na úplné licenčné informácie.