Hogyan írj hatásos dokumentációt a nyílt forráskódú projektedhez?

A dokumentáció minősége jelentős hatással lehet a projektedet kipróbáló (vagy az arra rátaláló) emberekre.

Sajnos a jó kód nem beszél önmagáért. Még a világ legsürgetőbb problémáját megoldó, legelegánsabban megtervezett és jól megírt kódbázis sem megy át magától. Neked, a nyílt forráskódú alkotónak, beszélned kell a kódodért, és életet kell lehelned alkotásodba. Itt jön képbe a technikai írás és dokumentáció.

Egy projekt dokumentáció generálja messze a legnagyobb forgalmat. Ez az a hely, ahol az emberek eldöntik, folytatják-e a projekteddel kapcsolatos tanulást, ismerkedést, vagy továbbállnak. Ezért az idő és az energiabefektetés a dokumentációba és a technikai írásba, a kezdeti lépésekre összpontosítva, csodákat fog tenni a projekted fogadtatása számára.

Az írás kellemetlen, vagy akár megfélemlítő lehet sokatok számára. A mérnökök a kódírásra vannak kiképezve, nem a kóddal kapcsolatos írásra. Sok ember második vagy akár harmadik nyelvként beszéli az angolt, és bizonytalannak vagy megfélemlítettnek érezheti magát angol szöveg írása közben. Én második nyelvként tanultam meg az angolt, számomra viszonylag könnyű volt, de nem mindenki mondhatja el ezt.

De nem kerülhetjük meg a valóságot, hogy ha egy projektnek széles, globális térnyerést szeretnél, az angol az a nyelv, amelyet muszáj használnod. Ne félj. Ezt a bejegyzést ezen kihívások tudatában írtam. Nem kell a következő Shakespeare-nek lenned, hogy az itt található javaslatokat hasznosnak találd.

Öt gyakorlati tipp

Itt van öt gyakorlati írási tipp, amelyet már ma felhasználhatsz. Talán fájdalmasan egyszerűnek és egyértelműnek tűnhetnek, mégis újra és újra figyelmen kívül vannak hagyva technikai írásokban.

1. Használj cselekvő igenemet: Cselekvő igenem: "Megváltoztathatod ezeket a beállításokat azáltal, hogy", a szenvedő szerkezettel szemben: "Ezek a beállítások megváltoztathatók azáltal, hogy".
2. Használj egyszerű, rövid mondatokat: Bár nem nyílt forráskódú projektek, de a Hemingway App és a Grammarly egyaránt hasznos segédeszközök.
3. Formázd könnyű olvashatóságra: Használj fejezetcímeket, felsorolásokat, hivatkozásokat, hogy tömbökbe törd az információt, hosszú, magyarázó paragrafusok helyett.
4. Tartsd meg vizuálisnak: Használj táblázatokat és grafikonokat, nem mondatokat, hogy több dimenzióval ábrázold az információt.
5. Figyelj a helyesírásra és nyelvtanra: Mindig, mindig, mindig ellenőrizd az elgépeléseket és nyelvtani hibákat, hogy csiszolj a szövegen.

Azáltal, hogy folyamatosan alkalmazod ezeket a tippeket az írásodban és munkafolyamatodban, két nagy célt érsz el vele: hatékony kommunikációt és bizalomépítést.

• Hatékony kommunikáció: A mérnökök nem akarnak hosszú, terjengős paragrafusokat olvasni dokumentációkban (a novellák vannak nekik erre a célra). Olyan hatékony technikai információkat vagy instrukciókat szeretnének (amikor útmutatóról van szó), amennyire csak lehet. Ezért az írásodnak száraznak és hasznosnak kell lennie. Ennek ellenére némi humor, hangulatjel, "pihe" használata rendben van, hogy némi személyiséget adj a projektednek, és még emlékezetesebbé tedd. Hogy ezt pontosan hogyan csinálod, az a te személyiségeden múlik.
• Bizalomépítés: A legértékesebb valuta, amit muszáj felhalmoznod, különösen a projekted építésének korai szakaszában, az a bizalom. A bizalom nem csak a kódod minőségéből jön, hanem az írás minőségéből is, ami a kódodról beszél. Ezért, kérlek használd ugyanazokat a csinosításokat az írásodra, amiket a kódodra használnál. Ez a fő indok a fenti ötös ponthoz (a helyesírás és nyelvtan ellenőrzése).

Kezdés a "kezdeti lépések" dokumentációval

Ezen alapvető technikák írásodba szövésével, a dokumentáció azon része, amivel a legtöbb időt kellene töltened, az az első lépések. Ez messze a legfontosabb rész, egy klasszikus példája a 80/20-as elvnek a gyakorlatban. A terméked webes forgalmának legnagyobb része a dokumentációra érkezik, ennek a legnagyobb része pedig a kezdeti lépésekhez. Ha remekül van összerakva, akkor rögtön kapni fogsz egy új felhasználót. Ha nem, akkor a látogató elkattint, és valószínűleg soha nem jön vissza.

Hogyan rakj össze jól egy kezdeti lépések részt? Az alábbi három lépéses folyamatot ajánlom:

1. Csináld meg feladatnak: Egy hatásos kezdeti lépések dokumentációnak feladat-orientáltnak kellene lennie - egy diszkrét mini-project, amit egy fejlesztő el tud érni. Nem kellene túl sok információt tartalmaznia a felépítési designról, fő koncepcióról és egyéb magas szintű információkról. Egy egyszeri, vizuális felépítési design rendben van, de ne szánj több paragrafust arra, hogy miért a te projekted a legjobban felépített megoldás. Az az információ máshova tartozik (bővebben erről lentebb). Ehelyett a kezdeti lépések résznek egy lépés és parancslistának kellene lennie... Nos, a kezdeti lépésekhez.
2. Befejezhető kevesebb mint 30 perc alatt: Itt a legfontosabb húzóerő, hogy a befejezéshez szükséges idő olyan alacsony legyen, amennyire csak lehet: 30 perc a felső határ. Ez az időlimit azt is feltételezi, hogy a felhasználónak relatív kis ismerete van a projekteddel kapcsolatban. Ezt fontos észben tartani. A legtöbb ember, akik a kezdeti lépések útmutatódon való végigmenéssel vesződnek, egy technikai közönség tagjai a projekted bizonytalan megértésével, de nem sokkal többel annál. Azért vannak ott, hogy kipróbáljanak valamit, mielőtt eldöntik, hogy töltsenek-e több időt a mélyebbre ásással. A "befejezési idő" egy mérőszám, amit mérned kellene, hogy folyamatosan fejleszd a kezdeti lépések útmutatódat.
3. Csinálj valami jelentőségteljeset: A "jelentőségteljes" a nyílt forráskódú projekten múlik. Fontos erősen elgondolkozni azon, hogy mi az, szilárdan feladatban meghatározni, és lehetővé tenni egy fejlesztőnek, aki befejezi a kezdeti lépések útmutatódat, hogy véghez vigye ezt a jelentőségteljes feladatot. Ennek a jelentőségteljes feladatnak muszáj, hogy közvetlenül a projekted értékéhez szóljon, egyébként a fejlesztők úgy fogják érezni, hogy vesztegették az idejüket.

Inspirációnak: Ha a projekted egy elosztott adatbázis projekt, akkor meglehet, hogy a "jelentőségteljes" azt jelenti, hogy az egész fürt (cluster) maradjon elérhető kiesések nélkül, ha kilősz néhány csomópontot (node). Ha a projekted adatelemzéssel vagy üzleti ismeretekkel kapcsolatos eszközzel kapcsolatos, akkor meglehet, hogy a "jelentőségteljes" egy dashboard generálása különböző vizualizációkkal, miután betöltött némi adatot. Bármit is jelentsen a "jelentőségteljes" a projektednek, gyorsan és helyileg elérhetőnek kellene lennie egy laptopon.

Egy jó példa a Linkerd Getting Started-je. A Linkerd egy szolgáltatási háló (service mesh) a Kuberneteshez és más keretrendszerekhez. Én kezdő vagyok a Kubernetesben, és még annál is kevésbé ismerős a service mesh-ben. Mégis mindenféle macera nélkül végigmentem a Linkerd Getting Started útmutatóján egy laptopon, és ez megízleltette velem, hogy miről is szól egy service mesh kezelése.

A fenti három lépéses folyamat egy hasznos keretrendszer lehet nagyon hatékony kezdeti lépések útmutató elkészítéséhez, egy mérhető módon. Kapcsolódik az idő-érték mérőhöz is, amikor egy nyílt forráskódú projekted termékesítéséről van szó.

Egyéb alapvető komponensek

Amellett, hogy figyelmesen kalibrálod és optimizálod a kezdeti lépések útmutatódat, van öt másik felső szintű komponens, ami ahhoz szükséges, hogy teljes értékű dokumentációt építs: felépítési design, gyártásbeli használati útmutató, felhasználási lehetőségek, referenciák, és ütemterv.

• Felépítési design: Ez egy mély-merülés a projekted felépítésébe és a design-nal kapcsolatos döntéseid mögötti elvekbe. Mindennel kapcsolatos részletek, amiket stratégiailag megmagyaráztál a kezdeti lépések útmutatódban. Ez a részleg egy nagy része a teljes termékmarketing tervednek. Ez a részleg általában tele van vizuális elemekkel, rajzokkal, és arra hivatott, hogy egy hétköznapi hobbistát szakértő rajongóvá változtasson, aki abban érdekelt, hogy időt fektessen a projektedbe hosszú távon.
• Gyártásbeli használati útmutató: Egy világnyi különbség van aközött, hogy kipróbálni valamit egy laptopon, vagy gyártásra használni. Rávezetni egy felhasználót, aki a projektedet komolyabban szeretné használni, egy fontos következő lépés. Gyártásbeli kezelési tudást bemutatni egy módja is annak, hogy hogyan vonzd be a kezdeti üzleti ügyfeleidet, akik kedvelhetik a technológia ígéretét, de nem tudják, vagy nem érzik magukat magabiztosnak arra, hogy gyártási környezetben használják.
• Felhasználási lehetőségek: A közösségi bizonyíték értéke egyértelmű, szóval a projektedet gyártásra használók listázása fontos. A kulcs itt az, hogy megbizonyosodj róla, hogy ez az információ könnyen megtalálható. Valószínűleg a második legnépszerűbb hivatkozás lesz a kezdeti lépések után.
• Referenciák: Ez a részleg elmagyarázza a projektedet részletesen, és lehetővé teszi a felhasználónak, hogy megvizsgálja és megértse mikroszkóp alatt. Ez "szótár"-ként is funkcionál, ahol az emberek információt keresnek fel, amikor szükséges. Néhány nyílt forráskódú alkotó mértéktelen időt tölt a projektje minden egyes apróságának és élének kihangsúlyozásával. A motiváció érthető, de onnantól kezdve szükségtelen, amikor az időd limitált. Hatásosabb egyensúlyt elérni a részletesség és a segítség szerzés módjai között: hivatkozás a közösségi fórumodra, Stack Overflow cédula, vagy egy külső GYIK (Gyakran Ismételt Kérdések) oldal is megteheti.
• Ütemterv: A jövőbeli elképzeléseid és terveid kiterítése egy vázlatos idővonallal megtarthatják a felhasználók érdeklődését és ösztönözöttségüket hosszabb távra. A projekted talán nem tökéletes jelenleg, de van egy terved a tökéletesítésére. Az ütemterv arra is remek hely, hogy összehozd a közösségedet egy erős ökoszisztéma építésére, szóval bizonyosodj meg róla, hogy hagysz egy hivatkozást, ahol az emberek hangot adhatnak gondolataiknak és véleményüknek az ütemtervvel kapcsolatban (fogok írni közösségépítési konkrétumokról a jövőben).

Meglehet, hogy még nincsenek meg neked teljesen ezek a komponensek, és néhány rész később valósul meg, mint mások, különösen a felhasználási lehetőségek. Azonban legyél szándékos ezeknek a kiépítésével időben. Ezen öt elemek megvalósítása a kritikus következő lépés a felhasználóid projektedbe való "utazásának", feltételezve, hogy jó tapasztalatuk van a kezdeti lépések útmutatóval.

Egy végső megjegyzés: Tegyél bele egy tiszta egymondatos állítást azzal kapcsolatban, hogy milyen licencet használsz (valószínűleg a kezdeti lépésekben, vagy az olvassel-ben, vagy valami más jól látható helyen). Ez az apróság a végfelhasználó oldaláról sokkal hatékonyabb használatba vételt eredményez.

Töltsd az időt 20%-át írással

Általánosságban az időd 10-20 %-át írással töltéssel javaslom. Kontextusba helyezés: Ha teljes munkaidőben dolgozol a projekteden, akkor körülbelül heti fél naptól egy napig. A még árnyaltabb pont itt az, hogy az írással kellene dolgoznod az átlagos munkafolyamatodban. szóval így rutinná válik, nem pedig egy elzárt munkává. Az idővel növekedő folyamat, az egész írás egyszerre történő megírásával szemben, az, ami segíteni fog, hogy a projekted elérje végső célját: húzóerő és bizalom.

Forrás: How to write effective documentation for your open source project.