ટેકનિકલ ડોક્યુમેન્ટેશન એ કોડ કમ્પાઈલ થયા પછી પૂરું કરી દેવાનું કોઈ ગૌણ કાર્ય નથી. તે દરેક સોફ્ટવેર પ્રોજેક્ટના કેન્દ્રમાં હોય છે, જે નક્કી કરે છે કે નવો ડેવલપર તેના પહેલા જ દિવસે બગ (bug) ફિક્સ કરી શકશે કે પછી વપરાશકર્તા પાંચ મિનિટની મૂંઝવણ પછી તમારા પ્રોડક્ટનો ત્યાગ કરી દેશે. સારા ડોક્યુમેન્ટ્સ વપરાશકર્તાઓને વાસ્તવિક કાર્યો પૂર્ણ કરવામાં મદદ કરે છે. તેઓ ભવિષ્યના મેન્ટેનર્સને સમજવામાં મદદ કરે છે કે કોઈ મોડ્યુલ શા માટે અસ્તિત્વ ધરાવે છે અને બધું બગાડ્યા વિના તેને કેવી રીતે બદલવું. તેમ છતાં, ઘણી બધી ટીમો ડોક્યુમેન્ટેશનને એક પૂરક વિચાર તરીકે જુએ છે, જે ઉતાવળમાં બનાવેલું README અથવા વર્ષોથી પડ્યું હોય તેવું વિકી પેજ હોય છે. ખરેખર ઉપયોગી ડોક્યુમેન્ટેશન લખવું એ એક કૌશલ્ય છે જેને તમે જાણીજોઈને સુધારી શકો છો.
લખતા પહેલા તમારા વાચકોને જાણો
તમે એક પણ હેડિંગ ટાઈપ કરો તે પહેલાં, નક્કી કરો કે કોણ વાંચી રહ્યું છે. કનેક્શન પૂલ સેટિંગ્સ શોધી રહેલા ડેટાબેઝ એડમિનિસ્ટ્રેટર અને React component props શોધી રહેલા ફ્રન્ટ-એન્ડ ડેવલપર વચ્ચે કોઈ સમાનતા નથી. અંતિમ વપરાશકર્તાઓને સ્ટેપ-બાય-સ્ટેપ સૂચનાઓ અને સ્ક્રીનશોટ્સની જરૂર હોય છે, આર્કિટેક્ચર ડાયાગ્રામની નહીં. તેઓ એ જાણવા માંગે છે કે PDF કેવી રીતે એક્સપોર્ટ કરવું, નહીં કે રેન્ડરિંગ પાઇપલાઇન કેવી રીતે કામ કરે છે. તમારી લાઇબ્રેરી ઇન્ટિગ્રેટ કરતા ડેવલપર્સને ચોક્કસ ફંક્શન સિગ્નેચર, એરર કોડ્સ અને કોપી-પેસ્ટ કરી શકાય તેવા સ્નિપેટ્સની જરૂર હોય છે. સિસ્ટમ એડમિનિસ્ટ્રેટર્સને ઇન્સ્ટોલેશન માટેની પૂર્વશરતો, એન્વાયરમેન્ટ વેરિયેબલ્સ અને ટ્રબલશૂટિંગ ફ્લોની જરૂર હોય છે જે સૌથી સામાન્ય નિષ્ફળતાના મોડ્સથી શરૂ થાય છે.
જો તમે એક જ મોટા લખાણ દ્વારા ત્રણેય જૂથોને સંતોષવાનો પ્રયાસ કરશો, તો દરેકનું નુકસાન થશે. અલગ અલગ માર્ગો બનાવો. એક જ પેજને પણ "ઓપરેટર્સ માટે" અને "ક્લાયન્ટ ડેવલપર્સ માટે" જેવા સ્પષ્ટ હેડિંગ્સ સાથે વ્યવસ્થિત રીતે વિભાજિત કરી શકાય છે. ધ્યેય એ છે કે "શું આ ફકરો મારા માટે છે?" એવું પૂછવાની માનસિક મૂંઝવણ દૂર કરવી.
બિનજરૂરી વિગતો દૂર કરો
સ્પષ્ટતા ચતુરાઈ કરતાં વધુ મહત્વની છે. ટૂંકા વાક્યોનો ઉપયોગ કરો. એક્ટિવ વોઇસનો ઉપયોગ કરો. "The database should be initialized by the user" કરતા "Initialize the database" વધુ સ્પષ્ટ છે. જ્યારે તમારે "idempotency" અથવા "serialization" જેવા ટેકનિકલ શબ્દનો ઉપયોગ કરવો પડે, ત્યારે તેને લખાણની વચ્ચે જ સમજાવો અથવા શબ્દકોશની લિંક આપો. પૂર્વજ્ઞાન હોવાનું માની લેવાની ભૂલ ન કરો.
એક વ્યવહારુ પરીક્ષણ: તમારો ફકરો મોટેથી વાંચવાનો પ્રયાસ કરો. જો તમારો શ્વાસ ખૂટી જાય, તો તેનો અર્થ છે કે વાક્ય ખૂબ લાંબું છે. બીજું પરીક્ષણ: અલંકારિક ક્રિયાપદોને સાદા ક્રિયાપદોથી બદલો. જો "utilize the API" જેવો શબ્દસમૂહ અર્થ ગુમાવ્યા વિના "use the API" બની શકતો હોય, તો તે ફેરફાર કરો. સાદી ભાષાનો અર્થ મૂર્ખામીભરી ભાષા એવો નથી. તેનો અર્થ છે કોર્પોરેટ વધારાના શબ્દો વગરની સચોટ ભાષા.
એવી સંરચના જે ખરેખર મદદરૂપ થાય
અવ્યવસ્થિત મેન્યુઅલ ન હોવા કરતા પણ વધુ સમય બગાડે છે. તમારા ડોક્યુમેન્ટેશનને એક ફનલ (funnel) તરીકે વિચારો. સૌથી ઉપર, એક ટૂંકો ઓવરવ્યુ મૂકો જે સમજાવે કે પ્રોજેક્ટ શું કરે છે અને કોણે તેની ચિંતા કરવી જોઈએ. ત્યારબાદ ઇન્સ્ટોલેશન સૂચનાઓ આપો જે વાચકની લોકલ સેટઅપ વિશે કંઈપણ માની લેતી ન હોય. પછી ટ્યુટોરિયલ્સ ઉમેરો જે શરૂઆતથી અંત સુધી સંપૂર્ણ અને વાસ્તવિક પરિસ્થિતિઓ દ્વારા માર્ગદર્શન આપે. ત્યારબાદ API રેફરન્સ આવે છે. આ વિસ્તૃત છતાં ઝડપથી વાંચી શકાય તેવું હોવું જોઈએ, જે મૂલ્ય અથવા ફંક્શન દ્વારા જૂથબદ્ધ હોવું જોઈએ, નહીં કે ફક્ત મૂળાક્ષરો મુજબ. છેલ્લે, ચોક્કસ સમસ્યાઓ માટે ટ્રબલશૂટિંગ ગાઈડ્સ મૂકો. "Connection refused" મેળવનાર વપરાશકર્તાને "Permission denied" જોનાર વપરાશકર્તા કરતા અલગ જવાબની જરૂર હોય છે. એરર્સને અમૂર્ત કેટેગરી દ્વારા નહીં, પણ મેસેજ અથવા સંદર્ભ દ્વારા જૂથબદ્ધ કરો.
લિસ્ટ અને કોડ બ્લોક્સ ઘન લખાણને તોડે છે અને વાચકોને તેમની જરૂરિયાત મુજબના ચોક્કસ કમાન્ડ શોધવામાં મદદ કરે છે. યોગ્ય રીતે મૂકેલું બુલેટ લિસ્ટ મૂંઝવણભર્યા ફકરાને ક્રમબદ્ધ ક્રિયાઓમાં બદલી શકે છે.
માત્ર કહો નહીં, બતાવો
અમૂર્ત સમજૂતીઓ વપરાશકર્તાઓને નિરાશ કરે છે. જો તમે કોઈ ટૂલ કેવી રીતે કન્ફિગર કરવું તેનું વર્ણન કરો છો, તો તેના ચોક્કસ ફાઇલ કન્ટેન્ટ બતાવો. ઇન્સ્ટોલેશન માટે, ઇનિશિયલાઇઝેશન માટે અને સામાન્ય કન્ફિગરેશન માટે કોડ સ્નિપેટ્સ આપો. સેમ્પલ ઇનપુટ્સ અને અપેક્ષિત આઉટપુટ્સ બાજુ-બાજુમાં બતાવો. જો તમારું API JSON રિટર્ન કરે છે, તો JSON બતાવો. જો CLI ટૂલ ટેબ્યુલર આઉટપુટ આપે છે, તો ટેબલ બતાવો. વર્કફ્લોનું વર્ણન એ ડેમોન્સ્ટ્રેશન સમાન છે એવું ક્યારેય માની ન લો.
સૌથી મહત્વનું, પ્રકાશિત કરતા પહેલા દરેક ઉદાહરણને ક્લીન એન્વાયરમેન્ટમાં ટેસ્ટ કરો. તમારા પોતાના સ્નિપેટને નવા કન્ટેનર અથવા વર્ચ્યુઅલ મશીનમાં કોપી કરીને જુઓ. જો તે કોઈ ડિપેન્ડન્સીનો ઉલ્લેખ કરવાનું ભૂલી જવાથી નિષ્ફળ જાય છે, તો તમે તમારી જાતને અનેક સમસ્યાઓથી બચાવી લીધી છે. ટેકનિકલ લેખનમાં નક્કર ઉદાહરણો રોકાણ પર સૌથી મોટું વળતર આપે છે કારણ કે તેઓ અનિશ્ચિતતાને ક્રિયામાં ફેરવે છે.
તેને જીવંત રાખો
ડોક્યુમેન્ટેશન કોડ કરતા પણ ઝડપથી ક્ષીણ થાય છે. એક મેથડ સિગ્નેચર બદલાય છે, ડિફોલ્ટ પોર્ટ બદલાય છે, ડિપેન્ડન્સી બદલાય છે, અને અચાનક તમારી સૂચનાઓ નિષ્ફળ જાય છે.