Dokumentasi ya kiufundi si kazi ya ziada unayomaliza baada ya kodi kukamilika (compile). Iko katikati ya kila mradi wa programu, ikiamua ikiwa msanidi programu mpya anaweza kurekebisha hitilafu (bug) katika siku yake ya kwanza au ikiwa mtumiaji ataacha kutumia bidhaa yako baada ya dakika tano za kuchanganyikiwa. Dokumentasi nzuri huwasaidia watumiaji kukamilisha kazi halisi. Huwasaidia watunza programu wa baadaye kuelewa kwa nini moduli fulani ipo na jinsi ya kuibadilisha bila kuharibu kila kitu. Hata hivyo, timu nyingi huchukulia dokumentasi kama jambo la baadae, kama README iliyoandaliwa kwa haraka, au ukurasa wa wiki ulioachwa kuliwa na muda. Kuandika dokumentasi yenye manufaa ya kweli ni ujuzi ambao unaweza kuuboresha kwa makusudi.
Jua Wasomaji Wako Kabla ya Kuandika
Kabla ya kuandika kichwa cha habari hata kimoja, amua ni nani anayesoma. Msimamizi wa hifadhidata (database administrator) anayetafuta mipangilio ya connection pool hana kitu cha pamoja na msanidi programu wa upande wa mbele (front-end developer) anayetafuta React component props. Watumiaji wa mwisho wanahitaji hatua zilizopewa namba na picha za skrini (screenshots), si michoro ya usanifu (architecture diagrams). Wanataka kujua jinsi ya kuuza nje (export) PDF, si jinsi mfumo wa rendering pipeline unavyofanya kazi. Wasanidi programu wanaounganisha maktaba (library) yako wanahitaji function signatures sahihi, msimbo wa hitilafu (error codes), na vipande vya kodi (snippets) vinavyoweza kunakiliwa na kubandikwa. Wasimamizi wa mifumo (system administrators) wanahitaji mahitaji ya awali ya usakinishaji, environment variables, na mifumo ya kutatua matatizo (troubleshooting flows) inayozingatia aina za kawaida za hitilafu.
Ukijaribu kuhudumia makundi haya yote matatu kwa maandishi marefu yasiyotenganishwa, kila mtu atapata hasara. Tengeneza njia tofauti. Hata ukurasa mmoja unaweza kugawanywa vizuri kwa vichwa vya habari vya wazi kama "Kwa waendeshaji" na "Kwa wasanidi programu wa mteja." Lengo ni kuondoa msuguano wa kiakili wa kujiuliza, "Je, aya hii imenengenezwa kwa ajili yangu?"
Punguza Kelele
Uwazi ni bora kuliko ujanja. Tumia sentensi fupi. Tumia sauti amilifu (active voice). "Anzisha hifadhidata" (Initialize the database) ni wazi zaidi kuliko "Hifadhidata inapaswa kuanzishwa na mtumiaji." Unapolazimika kutumia neno la kiufundi kama "idempotency" au "serialization," lifafanue ndani ya aya au weka kiungo cha kuelekea glosari. Usichukulie kuwa msomaji tayari anajua kila kitu.
Jaribio moja la vitendo: jaribu kusoma aya yako kwa sauti. Ukikosa pumzi, sentensi hiyo ni ndefu mno. Jaribio lingine: badilisha vitenzi vya kifahari na vitenzi rahisi. Ikiwa kirai kama "tumia API" (utilize the API) kinaweza kuwa "tumia API" (use the API) bila kupoteza maana, fanya mabadiliko hayo. Lugha rahisi haimaanishi lugha ya kijinga. Inamaanisha lugha sahihi iliyozuiwa na maneno mengi ya shirika yasiyo na maana.
Muundo Unaosaidia Kweli
Mwongozo usio na mpangilio unapoteza muda zaidi kuliko kutokuwa na mwongozo kabisa. Fikiria dokumentasi yako kama funeli. Juu kabisa, weka maelezo mafupi ya jumla yanayoeleza nini mradi unafanya na nani anapaswa kuujali. Fuatisha na maelekezo ya usakinishaji ambayo hayachukulihi kitu chochote kuhusu mipangilio ya ndani ya msomaji. Kisha ongeza mafunzo (tutorials) yanayopitisha hatua kamili na za kweli kuanzia mwanzo hadi mwisho. Marejeleo ya API yanafuata. Haya yanapaswa kuwa kamilifu lakini yanayoweza kusomwa kwa haraka, yakikundiwa kwa rasilimali au kazi (function) badala ya kuwekwa kwa mpangilio wa alfabeti. Hatimaye, weka miongozo ya kutatua matatizo inayoshughulikia dalili mahususi. Mtumiaji anayepata ujumbe wa "Connection refused" anahitaji jibu tofauti na yule anayeona "Permission denied." Kundi makosa kwa ujumbe au kwa muktadha, si kwa kategoria zisizo na dhahiri.
Orodha na vifungu vya kodi (code blocks) hupunguza msongamano wa maandishi na kuwaruhusu wasomaji kutafuta amri kamili wanayohitaji. Orodha ya nukta (bullet list) iliyowekwa vizuri inaweza kugeuza aya ya kuchanganyikiwa kuwa mfululizo wa hatua za kuchukua.
Onyesha, Usisimulie Tu
Maelezo ya kinadharia humtatiza mtumiaji. Ukielezea jinsi ya kuweka mipangilio ya zana, onyesha maudhui kamili ya faili. Toa vipande vya kodi (code snippets) kwa ajili ya usakinishaji, kwa ajili ya uanzishaji, na kwa ajili ya mipangilio ya kawaida. Onyesha mifano ya ingizo (inputs) na matokeo yanayotarajiwa (outputs) bega kwa bega. Ikiwa API yako inarudisha JSON, onyesha JSON hiyo. Ikiwa zana ya CLI inatoa matokeo ya jedwali, onyesha jedwali hilo. Usiamini kamwe kwamba maelezo ya mtiririko wa kazi ni sawa na onyesho la vitendo.
Muhimu zaidi, jaribu kila mfano katika mazingira safi kabla ya kuuchapisha. Nakili kipande chako cha kodi kwenye kontena (container) au mashine ya kidijitali (virtual machine) mpya. Ikiwa itafeli kwa sababu ulisahau kutaja utegemezi (dependency), umejiokoa na mfululizo wa matatizo. Mifano halisi hutoa faida kubwa zaidi ya uwekezaji katika uandishi wa kiufundi kwa sababu inageuza kutokuwa na uhakika kuwa hatua za kuchukua.
Iwe Hai Daima
Dokumentasi huchakaa haraka kuliko kodi. Method signature inabadilika, bandari ya kawaida (default port) inahamia, utegemezi (dependency) unabadilishwa, na ghafla maelekezo yako yanapeleka kwenye mwisho wa njia.