Ez a wikiHow megtanítja, hogyan kell dokumentációt írni egy nyílt forráskódú projekthez. Ezt a dokumentációt általában README fájlnak nevezik. A README egy szöveges vagy HTML dokumentum, amely a felhasználók és a fejlesztők számára egyaránt fontos információkat tartalmaz a projektről.
Lépések
1. lépés. Írja be a projekt címét
Amikor README -t ír a projektjéhez, először a projekt címét kell megadnia. A címmel együtt meg kell adni a legújabb verziószámot és a legutóbbi frissítés dátumát is.
2. lépés. Írja le a projekt leírását
A következő dolog, amelyet a README -be kell foglalnia, a projekt rövid leírása. Magyarázza el, mit tesz a projekt, miért létezik, és milyen problémákat old meg. Azt is megadhatja, hogy milyen speciális funkciókat, képernyőképeket, kódstílust, használt technológiát vagy keretrendszert, vagy bármi mást használ, amelyek hasznosak lehetnek a felhasználók és a fejlesztők számára.
3. lépés. Magyarázza el a projekt követelményeit
Ha a projektnek különleges követelményekre van szüksége a megfelelő működéshez, feltétlenül sorolja fel ezeket a követelményeket és utasításokat, vagy linket a telepítésükre vonatkozó utasításokhoz.
4. lépés. Vegyen be egy mintát a kódból
Adjon világos és tömör példát arra, hogy mire használják a projektet. A kódot könnyen ki kell találni a fejlesztőknek, és az API -nak jól láthatónak kell lennie.
5. lépés. Adja meg a telepítési utasításokat
Magyarázza el a felhasználóknak, hogyan hozzák üzembe szoftverüket lépésről lépésre. Az utasításoknak a lehető legtisztábbnak kell lenniük. Tegyük fel, hogy felhasználói nem ismerik a szoftverfejlesztést vagy a rendszergazdálkodást.
6. lépés. Magyarázza el, hogyan kell használni a szoftvert
Mondja el az embereknek, hogyan hozzák ki a legtöbbet a szoftverből. Adjon lépésről lépésre utasításokat a szoftver használatáról, valamint a különböző konfigurációs lehetőségekről és azok beállításáról.
7. lépés. Mondja el a felhasználóknak, hogyan kaphatnak technikai segítséget
Linkeket biztosít minden levelezőlistához, IRC -csatornához vagy közösségi fórumhoz, amelyekhez a felhasználók technikai segítségért fordulhatnak. Továbbá tájékoztassa a tapasztaltabb felhasználókat, hogy hová tegyen hibákat és ötleteket a projekt jobbá tétele érdekében.
Ha úgy találja, hogy sok ugyanazt a kérdést kapja a különböző felhasználóktól, érdemes a GYIK -ot (gyakran ismételt kérdéseket) felvenni a projektdokumentáció részeként
8. lépés. Magyarázza el, hogyan járulhat hozzá
Ha nyílt forráskódú projekten dolgozik, tudassa a felhasználókkal, hogyan járulhatnak hozzá a projekthez. Magyarázza el a rendelkezésére álló szabványokat, és adjon néhány útmutatást a lehetséges közreműködőknek.
9. lépés. Sorolja fel a krediteket
Mindig adjon hitelt ott, ahol esedékes. Feltétlenül tüntesse fel az összes közreműködő nevét, valamint az esetlegesen használt harmadik féltől származó könyvtárakra vagy programokra mutató linkeket. Mellékeljen linkeket bármilyen inspirációhoz, amelyet a projekt építése során kapott.
10. lépés. Adja meg elérhetőségeit
Az emberek több okból is kapcsolatba léphetnek Önnel. Feltétlenül adjon meg egy érvényes e -mail címet, amellyel az emberek kapcsolatba léphetnek Önnel.
Egyes országok a törvény értelmében további információkat, például postacímet vagy cégnevet kérhetnek
11. lépés. Adja meg a licencadatokat
Fontos, hogy a felhasználók tudják, hogyan kapják meg a projekt licencét. Rengeteg szabványos licenc található az interneten, amelyeket használhat. Magyarázza el, hogy a projekt milyen licencet használ, valamint az esetlegesen használt külső könyvtárak vagy programok licenceit.
Nem kell magyaráznia a teljes licencet a dokumentációban. Csak tájékoztassa a felhasználókat arról, hogy milyen licencet használ a projekt, és adja meg a linket a teljes licencinformációhoz
12. lépés. Sorolja fel a projekt összes verzióját
Feltétlenül készítsen listát a projekt összes korábbi verziójáról, és írjon egy rövid leírást arról, hogy milyen módosításokat hajtott végre az egyes verziókhoz.
Tippek
- Jó gyakorlat, ha a projekt fejlesztése előtt elkezdi írni a README fájlt. Ez segít átgondolni a projektet és azt, hogy mit kell megvalósítania. Segíteni fog olyan iránymutatások kidolgozásában, amelyeket közölhet más közreműködőkkel, és motiváltabb lesz a README fájl megírásához a projekt elején.
- Győződjön meg róla, hogy gyakran frissíti a README fájlt és egyéb dokumentációkat, amikor a projekten dolgozik.
- Ha a README fájl hosszabb, mint egy oldal, külön dokumentumként írhatja a hosszabb szakaszokat, például a telepítési utasításokat, a felhasználói útmutatót és a GYIK -ot. Feltétlenül készítsen tartalomjegyzéket az összes projektdokumentációhoz, és adjon linket a README fájl megfelelő dokumentációjához.