A termékcsapatoknak és a szoftvercsapatoknak egyaránt van egy közös problémája: a dokumentáció.
A termékdokumentáció a felhasználónak szóló kézikönyveket és útmutatókat jelenti, amelyek elmagyarázzák a termék munkafolyamatát és felhasználói felületét. Hogyan lehet az átlagfelhasználó produktív ezzel a termékkel? Ebben az értelemben a termékdokumentáció a szoftvertermékekre is alkalmazható.
A szoftverdokumentáció egy szoftvertermék mögöttes technológiáira, előfeltételeire és konfigurálható tulajdonságaira vonatkozik. Hogyan konfigurálják, felügyelik, hosztolják és telepítik az informatikai rendszergazdák a szoftverterméket a felhasználók számára? Ez a fajta dokumentáció fontos, különösen akkor, ha több verzió vagy ág is bekerül a keverékbe.
Bizonyos értelemben a termékdokumentáció olyan, mintha valakit megtanítanánk autót vezetni. A kormány elfordítja az autót, a gázpedál mozgatja az autót, a fékpedál megállítja az autót. A szoftverdokumentáció megtanítja valakinek, hogyan működik az autó. A kerék az első tengelyhez kapcsolódik, amely elfordítja az első kerekeket, hogy megváltoztassa a menetirányt; a gázpedál növeli a levegő áramlását a motorhoz, amely több üzemanyagot szív be, nyomatékot és lóerőt generálva.
Mindkét dokumentációtípus fontos. Az egyik a felhasználókat, a másik a rendszergazdákat és a fejlesztőket oktatja. Remek dolog megmutatni az embereknek, hogyan kell autót vezetni, de ha senki sem tudja, hogyan működik az autó, mi történik, ha az autó lerobban?
Kisebb különbségek a termék- és a szoftverdokumentáció között
A termék- és a szoftverdokumentációban vannak kisebb különbségek, amelyekkel tisztában kell lenni:
Szoftver- és termékdokumentáció: Célközönség és személyiség
A termékdokumentáció egyetlen célközönségnek szól: a felhasználónak. Feltételezi, hogy a felhasználó nem rendelkezik műszaki ismeretekkel, és egyszerű angol nyelven, minimális szakzsargonnal kommunikál. Hasonlóan a műszaki szakmunkásképzéshez és az egyetemi diplomához, arra oktatja az embereket, hogyan kell dolgokat csinálni, és kevésbé összpontosít az elméleti vagy koncepcionális ismeretekre.
A szoftverdokumentáció az informatikai rendszergazdákat, mérnököket és fejlesztőket célozza meg. A szoftverek tervezésével és architektúrájával, parancssori beállítási utasításokkal, API- és integrációs támogatással, adatkezeléssel és jelentéstétellel, hálózati topológiával foglalkozik - alapvetően a gépezetet működtető fogaskerekekkel. Ezek a dokumentumok egy olyan egységes igazságforrást (SSOT) alkotnak, amelyre az informatikai személyzet hivatkozhat a szoftveralkalmazás felügyelete és hibaelhárítása során.
Szoftver- és termékdokumentáció: Frissítési gyakoriság
A szoftver dokumentációját következetesen frissíteni kell, amint az új commitok beolvadnak a fő kiadási csatornába. A szoftverdokumentációnak ki kell emelnie az új funkciókat és parancsokat, és ki kell törölnie a régi funkciókat. Dokumentálni kell az új vagy változó függőségeket, és tisztázni kell a funkciók támogatását az összes célplatformon - például ha egy funkció Windowson működik, de Linuxon nem.
A termékdokumentációt csak akkor kell frissíteni, ha a mögöttes szoftverszerkesztés változást hoz a munkafolyamatban vagy a használhatóságban. Egy fejlesztő megváltoztatja a fizetési átjáró kódját, de a felhasználók számára a fizetési folyamat nem változik, így nincs szükség frissítésre.
Ez a szoftvertermék-dokumentáció természetes hierarchiáját mutatja. A technikai szoftverdokumentáció képezi az alapot, és a későbbi termékdokumentáció erre az alapra épül. Ezért a hangsúlyt a nagyszerű szoftverdokumentáció készítésére kell helyezni, mivel az még nagyobb termékdokumentációt szül.
Példa a termék- és szoftverdokumentáció formázási kereteire
Egy termékdokumentáció követheti ezt a keretrendszert:
-
- Termék neve*
-
- A termék céljának áttekintése*
-
Elhelyezési útmutató
-
-
-
- funkció magyarázata és képek*
-
-
-
- Feature 2 magyarázat és képek
-
- Ügyféltámogatási linkek*
Hasonlóképpen, egy szoftver dokumentációja is követheti ezt a keretrendszert:
-
szoftver neve
-
- A szoftver céljának áttekintése*
-
Szoftverfüggőségek
-
- Telepítési útmutató*
-
- Function 1 magyarázat és képek
-
- Magyarázat és képek a 2. funkcióhoz
-
- Technikai támogatási linkek
Nyilvánvaló, hogy ez a két dokumentációtípus szorosan kapcsolódik egymáshoz, és hasonló struktúrát követ. Ez azt jelenti, hogy a termék- és szoftvercsapatok sokat tanulhatnak egymástól, és sok lehetőséget rejtenek magukban, amikor a dokumentáción együttműködve dolgoznak.
A termék- és szoftverdokumentációs csapatok kiegészíthetik egymást
A termék- és a szoftverdokumentáció között erős hasonlóságok vannak. Ez felveti a kérdést: tudnak-e együtt dolgozni a termék- és a szoftvercsapatok?
Igen, össze tudnak, és össze is kell, hogy dolgozzanak!
A szoftvercsapatok értik a műszaki zsargont és a mögöttes technológiákat. A termékcsapatok megértik, hogy a felhasználók mit látnak, mit akarnak és mire van szükségük; a felhasználói élményt. A szoftverdokumentáció írói részletes technikai információkat tudnak nyújtani, a termékdokumentáció írói pedig felhígíthatják a technikai részleteket a laikus közönség számára.
Képzelje el, hogy megpróbál valamit laikusok számára érthetően elmagyarázni, anélkül, hogy rendelkezne a laikusok számára érthető megfogalmazáshoz szükséges magas szintű ismeretekkel. Ez történik, amikor a termékdokumentáció a szoftverdokumentáció előtt készül.
Mi a kvantummechanika? Valószínűleg Schrödinger macskája az első gondolat, ami eszébe jut! De mi köze van a kvantummechanikának a macskákhoz? A felhasználó számára nem fontos. Egy fizikusnak viszont mindent jelent.
Kezdje a szoftverdokumentációval, és fejezze be a jobb termékdokumentációval a Docsie-ban
Összefoglalva, számos előnye van annak, ha a szoftverdokumentációt mintaként használjuk a későbbi termékdokumentációhoz. A szoftverdokumentációnak egyetlen igazságforrásként kell működnie az informatikai személyzet és a termékdokumentációt írók számára. A termékdokumentáció megírása után a termékdokumentáció-írók tisztánlátással és megértéssel rendelkeznek ahhoz, hogy egyszerűsítsék és felhasználóbarát tudást osszanak meg az ügyfelekkel, a lektoráláshoz és a minőségbiztosításhoz szükséges technikai útmutatással.
Egyszerűen, ha nagyszerű szoftverdokumentációval kezdi, az írói még jobb termékdokumentációt készíthetnek!
Kezdjen el olyan dokumentációt készíteni, amely segít ügyfeleinek többet tenni. Iratkozzon fel a Startup tervünkre (forever free!)](https://www.docsie.io/pricing/) és nyújtson gyönyörködtető dokumentációt a Docsie-val!