A projekt dokumentációjának egyszerű elkészítése: 12 lépés

Tartalomjegyzék:

A projekt dokumentációjának egyszerű elkészítése: 12 lépés
A projekt dokumentációjának egyszerű elkészítése: 12 lépés

Videó: A projekt dokumentációjának egyszerű elkészítése: 12 lépés

Videó: A projekt dokumentációjának egyszerű elkészítése: 12 lépés
Videó: PLC, egyszerűbb mint gondolnád! ◆ Az alapok 2024, Március
Anonim

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

Dokumentáció elkészítése a projekthez 1. lépés
Dokumentáció elkészítése a projekthez 1. lépés

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.

Dokumentáció elkészítése a projekthez 2. lépés
Dokumentáció elkészítése a projekthez 2. lépés

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.

Dokumentáció elkészítése a projekthez 3. lépés
Dokumentáció elkészítése a projekthez 3. lépés

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.

Dokumentáció elkészítése a projekthez 4. lépés
Dokumentáció elkészítése a projekthez 4. lépés

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.

Dokumentáció elkészítése a projekthez 5. lépés
Dokumentáció elkészítése a projekthez 5. lépés

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.

Dokumentáció elkészítése a projekthez 6. lépés
Dokumentáció elkészítése a projekthez 6. lépés

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.

Dokumentáció elkészítése a projekthez 7. lépés
Dokumentáció elkészítése a projekthez 7. lépés

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

Dokumentáció elkészítése a projekthez 8. lépés
Dokumentáció elkészítése a projekthez 8. lépés

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.

Dokumentáció elkészítése a projekthez 9. lépés
Dokumentáció elkészítése a projekthez 9. lépés

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.

Dokumentáció elkészítése a projekthez 10. lépés
Dokumentáció elkészítése a projekthez 10. lépés

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

Dokumentáció elkészítése a projekthez 11. lépés
Dokumentáció elkészítése a projekthez 11. lépés

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

Dokumentáció elkészítése a projekthez 12. lépés
Dokumentáció elkészítése a projekthez 12. lépés

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.

Ajánlott: