નફો:
- AI સાથે લક્ષ્ય પ્રેક્ષકો અને સ્ત્રોત પર આધારિત README, docstring અને ચેન્જલોગ ડ્રાફ્ટ્સ બનાવવાની ક્ષમતા
- દસ્તાવેજીકરણમાં 'શું/કેવી રીતે' અને 'શા માટે' સ્તરોને અલગ કરવાની અને માનવ તરીકે 'શા માટે' ઉમેરવાની ક્ષમતા
- ઇન્સ્ટોલેશન સ્ટેપ્સને વ્યક્તિગત રીતે ચલાવીને અને દસ્તાવેજને કોડ ફેરફારનો એક ભાગ બનાવીને ચકાસો
સૉફ્ટવેરનો સૌથી વધુ વારંવાર ઉપેક્ષિત પરંતુ સૌથી લાંબો સમય ચાલતો ભાગ દસ્તાવેજીકરણ છે. કોડ મહિનાઓ પછી પણ વાંચી શકાય છે; જેણે લખ્યું હતું તે જતો રહ્યો છે, સંદર્ભ ભૂલી ગયો છે, અને જે લખ્યું હતું તે જ બાકી છે. એક સારો README (પ્રારંભિક દસ્તાવેજ જે સમજાવે છે કે પ્રોજેક્ટ શું છે અને તેને કેવી રીતે ઇન્સ્ટોલ કરવું અને તેને કેવી રીતે ચલાવવું), સમજૂતીત્મક કોડ ટિપ્પણીઓ અને અપ-ટુ-ડેટ API દસ્તાવેજીકરણ (એક સંદર્ભ જે ઇન્ટરફેસનો ઉપયોગ કેવી રીતે કરવો તે સમજાવે છે) ટીમની ગતિ સીધી રીતે નક્કી કરે છે. AI દસ્તાવેજીકરણમાંથી ઘણી બધી “લેખન થાક” લે છે — પરંતુ તે એક છટકું સાથે આવે છે: AI કોડમાંથી અનુમાન લગાવી શકે છે કે તે શું કરે છે, પરંતુ ઘણીવાર તે શા માટે તે રીતે કરવામાં આવ્યું છે તે જાણી શકતું નથી.
આ એકમમાં, તમે શીખશો કે કેવી રીતે README, કોડ ટિપ્પણી, docstring (ફંક્શન/વર્ગ દીઠ લખાયેલ ટિપ્પણી બ્લોક), API દસ્તાવેજ અને AI સાથે ચેન્જલોગ કેવી રીતે બનાવવું; અને દસ્તાવેજીકરણના સૌથી મૂલ્યવાન ભાગને માનવીય રીતે કેવી રીતે સાચવી શકાય: "શા માટે."
"શું" અને "શા માટે" વચ્ચેનો તફાવત
દસ્તાવેજીકરણના બે સ્તરો છે. પ્રથમ શું/કેવી રીતે છે: "આ કાર્ય સૂચિને સૉર્ટ કરે છે", "ઇન્સ્ટોલ કરવા માટે આ આદેશ ચલાવો". આ કોડ અને બંધારણમાંથી કાઢી શકાય છે; AI અહીં શ્રેષ્ઠ છે. બીજું, શા માટે: "અમે આ સેવાને સિંક્રનસને બદલે અસુમેળ શા માટે બનાવી", "આ મર્યાદા મૂલ્ય 30 સેકન્ડ શા માટે છે", "અમે આ લાઇબ્રેરીને બીજા પર શા માટે પસંદ કરી". આ કોડમાં લખેલા નથી; તે ડિઝાઇન નિર્ણયો, અવરોધો અને ભૂતકાળની પીડાનું ઉત્પાદન છે.
AI ને "શા માટે" ખબર નથી; શ્રેષ્ઠ રીતે, તે વાજબી અનુમાન લગાવે છે - જે ખતરનાક છે, કારણ કે ખોટું કારણ કોઈ કારણ વિના ખરાબ છે. તેથી શ્રમનું વિભાજન સ્પષ્ટ છે: AI "શું/કેવી રીતે" ડ્રાફ્ટ કરે છે, તમે "શા માટે" ઉમેરો છો. સૌથી મૂલ્યવાન ટિપ્પણી એ છે જે કહે છે કે કોડ શું કહી શકતો નથી.
ટીપ: કોડ પોતે જ સ્પષ્ટપણે શું કહે છે તે ટિપ્પણી સાથે પુનરાવર્તન કરશો નહીં (જેમ કે i = i + 1 // i વડે એક વધારો). AI કેટલીકવાર આવી બિનજરૂરી ટિપ્પણીઓ ઉત્પન્ન કરે છે; તેમને દૂર કરો અને તમારી શક્તિ "શા માટે" ટિપ્પણીઓમાં સમર્પિત કરો.
સ્ટેપ બાય સ્ટેપ: AI સાથે ડોક્યુમેન્ટેશન જનરેશન
- લક્ષ્ય પ્રેક્ષકોનો ઉલ્લેખ કરો. "એક વિકાસકર્તા હમણાં જ શરૂઆત કરે છે," "બાહ્ય ટીમ કે જે આ API નો ઉપયોગ કરશે," "ભવિષ્યનો હું" — પ્રેક્ષકો ભાષા અને ઊંડાણ માટે ટોન સેટ કરે છે.
- સ્ત્રોત આપો. પ્રોમ્પ્ટમાં સંબંધિત કોડ, હાલની README, ઉદાહરણ વપરાશ ઉમેરો. અનસોર્સ્ડ ડોક્યુમેન્ટ એ ફેબ્રિકેશન માટેનું આમંત્રણ છે.
- લાદવાની રચના. README માટે માનક વિભાગો (હેતુ, સ્થાપન, ઉપયોગ, રૂપરેખાંકન, યોગદાન), ડોકસ્ટ્રિંગ માટે પ્રોજેક્ટ ફોર્મેટ.
- "શા માટે" જગ્યાઓને ચિહ્નિત કરો. AI ને એવા નિર્ણયોને ચિહ્નિત કરવા માટે કહો કે જેના માટે તે તર્ક જાણતો નથી કારણ કે "અહીં 'શા માટે' નોંધ જરૂરી છે"; પછી તમે તે ખાલી જગ્યાઓ ભરો.
- ચકાસો. ખરેખર સ્થાપન પગલાંઓ ચલાવો; નમૂના કોડનો પ્રયાસ કરો. એક README જે કામ કરતું નથી તે કોઈ README કરતાં ખરાબ છે.
ત્રણ મિની કેસ
કેસ 1 — README ઑનબોર્ડિંગને ઝડપી બનાવ્યું. ઓપન સોર્સ ટૂલનું README ખૂટે છે; નવા યોગદાનકર્તાઓએ સરેરાશ 2 કલાક માટે ઇન્સ્ટોલેશન સાથે સંઘર્ષ કર્યો. ટીમે AI ને ઇન્સ્ટોલેશન સ્ક્રિપ્ટ્સ અને package.json આપી અને એક સ્ટ્રક્ચર્ડ README નો મુસદ્દો તૈયાર કર્યો, પછી ક્લીન મશીન પર જાતે જ સ્ટેપ્સ ચલાવ્યા અને બે ખૂટતી ડિપેન્ડન્સી ઉમેરી. અનુગામી યોગદાનકર્તાઓ માટે ઇન્સ્ટોલેશન સમય સરેરાશ 25 મિનિટ સુધી ઘટી ગયો.
કેસ 2 - બનાવેલ "શા માટે" છટકું. એક વિકાસકર્તાએ AI ને સમયસમાપ્તિ મૂલ્ય (સમયસમાપ્તિ=30) ની બાજુમાં ટિપ્પણી માટે પૂછ્યું. AI એ "ઉચ્ચ નેટવર્ક લેટન્સી સહન કરવા માટે" વાજબી પરંતુ ખોટું સમર્થન લખ્યું છે; વાસ્તવિક કારણ ડાઉનસ્ટ્રીમ સેવાની કરાર આધારિત 30-સેકન્ડની મર્યાદા હતી. ખોટા અર્થઘટનને કારણે અનુગામી વિકાસકર્તાએ બિનજરૂરી રીતે મૂલ્યમાં વધારો કર્યો, જે એક ઘટના તરફ દોરી ગયો. પાઠ: કોડ માલિકે વાજબીતા ચકાસવી આવશ્યક છે.
કેસ 3 — ડોકસ્ટ્રિંગ સ્ટાન્ડર્ડ સ્વચાલિત થઈ ગયું છે. 40 ફંક્શન્સ સાથેના સહાયક મોડ્યુલમાં કોઈ દસ્તાવેજ નથી. AI ને પ્રોજેક્ટ ફોર્મેટ (Google શૈલી) આપવામાં આવ્યું હતું અને દરેક કાર્ય માટે પેરામીટર, વળતર અને અપવાદ વર્ણનો તૈયાર કર્યા હતા; વિકાસકર્તાએ આની સમીક્ષા કરી અને કેટલીક ખોટી પ્રકારની ઘોષણાઓ સુધારી. 40 કાર્યોનું દસ્તાવેજીકરણ લગભગ અડધા દિવસથી ઘટીને એક કલાક થઈ ગયું.
ચાર નકલ કરી શકાય તેવા નમૂનાઓ
સ્ટ્રક્ચર્ડ README ડ્રાફ્ટ:
લક્ષ્ય પ્રેક્ષકો: {{દા.ત. new contributor}}. નીચે આપેલી ફાઇલોના આધારે ડ્રાફ્ટ README લખો. વિભાગો: હેતુ, વિશેષતાઓ, જરૂરિયાતો, સ્થાપન, કામગીરી, રૂપરેખાંકન, પરીક્ષણ, યોગદાન. વાસ્તવિક ફાઇલોમાંથી ઇન્સ્ટોલેશન/ચાલતી આદેશો બહાર કાઢો; ફિટિંગ. તમને ખાતરી ન હોય તેવા સ્થાનોને "[VERIFY]" વડે ચિહ્નિત કરો. સ્ત્રોત: {{package.json/scripts/sample code}}
Docstring/API સંદર્ભ:
{{project style: Google/NumPy/JSDoc}} ફોર્મેટમાં આ ફંક્શન્સ માટે docstring લખો: ટૂંકો સારાંશ, પરિમાણો (પ્રકાર + અર્થ), વળતર, અપવાદો ફેંકવામાં, 1 ટૂંકું ઉદાહરણ. કોડ સ્પષ્ટપણે શું કહે છે તેનું પુનરાવર્તન કરશો નહીં. "શા માટે" જરૂરી હોય તેવા ડિઝાઇન નિર્ણયોને "[શા માટે જરૂરી]" તરીકે ચિહ્નિત કરો, બનાવટી સમર્થન ન લખો.{{code}}
"શા માટે" ટિપ્પણી માટે જગ્યાઓ દૂર કરો:
આ કોડમાં, આગળનો વિકાસકર્તા પૂછી શકે છે કે "આવું કેમ છે?" (જાદુઈ સંખ્યાઓ, અસામાન્ય નિર્ણયો, ઉકેલ). દરેક માટે એક ટિપ્પણી સ્કેલેટન આપો, પરંતુ તર્ક ખાલી છોડી દો; હું સમર્થન ભરીશ.{{code}}
ચેન્જલોગ/PR સ્ટેટમેન્ટ:
નીચેના તફાવતમાંથી {{ચેન્જલોગ એન્ટ્રી / PR વર્ણન}} લખો. ફોર્મેટ: શું બદલાયું (વપરાશકર્તા ભાષામાં), શા માટે (સમસ્યા: {{...}}), બ્રેકિંગ ફેરફાર (જો કોઈ હોય તો), શું તેનું પરીક્ષણ કરવામાં આવ્યું છે. લક્ષ્ય પ્રેક્ષકો માટે ટેક્નિકલ કલકલને સમાયોજિત કરો.{{diff}}
નબળા પ્રોમ્પ્ટ / મજબૂત પ્રોમ્પ્ટ
નબળા: "આ પ્રોજેક્ટ માટે એક README લખો."
મજબૂત: "લક્ષ્ય પ્રેક્ષકો: એક વિકાસકર્તા પ્રથમ વખત આ રેપોનું ક્લોનિંગ કરે છે. જોડાયેલ પેકેજ.json, docker-compose.yml અને સ્ક્રિપ્ટ્સ/ ફોલ્ડરના આધારે, હેતુ, આવશ્યકતાઓ, ઇન્સ્ટોલેશન, ઑપરેશન, પરીક્ષણ, યોગદાન વિભાગો સાથેનો ડ્રાફ્ટ README લખો. તેમાંથી આદેશો બહાર કાઢો જ્યાં તમે આ ફાઇલો સાથે ચિહ્નિત કરશો નહીં; [ચકાસો]."
મજબૂત સંસ્કરણ પ્રેક્ષકો, સ્ત્રોત, માળખું અને "તેને બનાવો, તેને ચિહ્નિત કરો" નિયમ આપે છે; જેથી દસ્તાવેજ વાસ્તવિક ફાઈલો પર આધારિત હોય અને ચકાસવાના સ્થાનો સ્પષ્ટપણે જોઈ શકાય.
દસ્તાવેજનો પ્રકાર
AI સારું કરે છે
માનવ ઉમેરે/ચકાસે છે
README ઇન્સ્ટોલેશન
પગલું રૂપરેખા
પગલાંઓ ચલાવો અને પુષ્ટિ કરો
ડોકસ્ટ્રિંગ/API
માળખું, પરિમાણ, પ્રકાર
સાચો પ્રકાર અને "શા માટે"
કોડ ટિપ્પણી
"તે શું કરી રહ્યો છે" સારાંશ
"આ કેમ છે" વાજબીપણું
ચેન્જલોગ/PR
પ્રથમ ડ્રાફ્ટ
અસર અને ચોકસાઈ
આર્કિટેક્ચરલ નિર્ણય (ADR)
હાડપિંજર
વાસ્તવિક નિર્ણયો અને સમાધાન
દસ્તાવેજીકરણ માટે જાળવણીની જરૂર છે
દસ્તાવેજનું સૌથી ખતરનાક પાસું એ છે કે જ્યારે તે ખોટા હોવા છતાં તે સાચું દેખાય છે. જ્યારે કોડ બદલાય છે અને દસ્તાવેજ અપડેટ થતો નથી, ત્યારે તે રીડરને સક્રિયપણે ગેરમાર્ગે દોરે છે. AI અપડેટ કરવાનું સરળ બનાવે છે: એક તફાવત રજૂ કરો અને પૂછો કે "આ ફેરફાર દસ્તાવેજના કયા ભાગોને અસર કરે છે?" તમે પૂછી શકો છો. પરંતુ તે પ્રક્રિયા છે જે અદ્યતનતાની ખાતરી કરે છે — દસ્તાવેજીકરણ અપડેટને કોડ ફેરફારનો ભાગ બનાવો (PR ની સ્વીકૃતિ માપદંડ). AI વેગ આપે છે; ટીમ શિસ્ત બનાવે છે.
સાવધાન: README માં ઇન્સ્ટોલેશન સ્ટેપ્સ ચકાસ્યા વિના પ્રકાશિત કરશો નહીં. "કદાચ કાર્યકારી" દસ્તાવેજ નવા ડેવલપરનો પ્રથમ દિવસ બગાડી શકે છે અને વિશ્વાસને ખતમ કરી શકે છે. સ્વચ્છ વાતાવરણમાં જાતે પગલાંઓ ચલાવો.
સામાન્ય ભૂલો
- AI માં ફિટ થવા માટે "શા માટે" મેળવવું. ખોટા વાજબીપણું કોઈ વાજબીતા કરતાં વધુ ખરાબ છે; કોડ માલિકે ડિઝાઇન કારણ લખવું જોઈએ.
- ઇન્સ્ટોલેશનના પગલાંની ચકાસણી કરી રહ્યાં નથી. README જે કામ કરતું નથી તે વિશ્વાસનો નાશ કરે છે.
- કોડનું પુનરાવર્તન કરતી બિનજરૂરી ટિપ્પણી. તે અવાજ ઉત્પન્ન કરે છે, વાસ્તવિક "શા માટે" અર્થઘટનને અસ્પષ્ટ કરે છે.
- લક્ષ્ય પ્રેક્ષકોનો ઉલ્લેખ નથી. એક દસ્તાવેજ જે અસ્પષ્ટ છે કે તે કોના માટે લખાયેલ છે તે શિખાઉ અથવા નિષ્ણાત માટે કોઈ કામનું નથી.
- અપડેટને પ્રક્રિયાથી અલગ કરી રહ્યાં છીએ. જો દસ્તાવેજ કોડ સાથે અપડેટ કરવામાં ન આવે તો તે ઝડપથી ભ્રામક બની જાય છે.
સારાંશમાં
AI દસ્તાવેજીકરણમાંથી મોટાભાગનો યાંત્રિક બોજ ઉઠાવે છે: ઝડપી ડ્રાફ્ટ્સ README, docstring, API સંદર્ભ, ચેન્જલોગ અને PR વર્ણન. પરંતુ તે "શા માટે", જે સૌથી મૂલ્યવાન સ્તર છે તે જાણી શકતું નથી, અને તેને બનાવવું જોખમી છે. શ્રમનું વિભાજન સ્પષ્ટ છે: AI "શું/કેવી રીતે" ઉત્પન્ન કરે છે, તમે "શા માટે" ઉમેરો છો. પ્રેક્ષકોનો ઉલ્લેખ કરો, સંસાધનો પ્રદાન કરો, માળખું લાગુ કરો, ફિટ થવા માટે સ્થાનો ચિહ્નિત કરો અને દરેક ઇન્સ્ટોલેશન સ્ટેપને જાતે ચલાવીને ચકાસો. દસ્તાવેજીકરણને કોડ ફેરફારનો અભિન્ન ભાગ બનાવો.
એપ્લિકેશન કાર્ય
એક મોડ્યુલ અથવા નાનો પ્રોજેક્ટ પસંદ કરો કે જેનું દસ્તાવેજીકરણ ખૂટે છે અથવા જૂનું છે. પ્રથમ AI માંથી “સ્ટ્રક્ચર્ડ README ડ્રાફ્ટ” (અથવા docstring) ટેમ્પલેટ સાથે રૂપરેખા બનાવો; સ્ત્રોત અને લક્ષ્ય પ્રેક્ષકો આપવા માટે ખાતરી કરો. પછી દરેક બિંદુ પર જાઓ જ્યાં AI એ ચિહ્નિત કર્યું છે [ચકાસવું] અથવા [શા માટે જરૂરી છે]: વાસ્તવમાં સેટઅપ સ્ટેપ્સ ચલાવો અને તમારા પોતાના જ્ઞાન સાથે "શા માટે" ડિઝાઇન ભરો. નોંધ કરો કે કેટલા પગલાઓ ઠીક કરવાની જરૂર છે અને તમે કેટલા "શા માટે" ઉમેર્યા છે.
ચેકલિસ્ટ
- [ ] દસ્તાવેજીકરણમાં, હું "શું/કેવી રીતે" અને "શા માટે" સ્તરોને અલગ પાડું છું.
- [ ] હું AI ને "શા માટે" બનાવતો નથી, હું તેને જાતે ઉમેરું છું.
- [ ] હું લક્ષ્ય પ્રેક્ષકો અને વાસ્તવિક સ્ત્રોત ફાઇલોને પ્રોમ્પ્ટ આપું છું.
- [ ] હું AI દ્વારા ચિહ્નિત થયેલ [ચકાસણી] પોઈન્ટ્સને વ્યક્તિગત રીતે એક્ઝિક્યુટ કરીને ચકાસું છું.
- [ ] હું બિનજરૂરી ટિપ્પણીઓને દૂર કરું છું જે કોડનું પુનરાવર્તન કરે છે.
- [ ] હું દસ્તાવેજીકરણ અપડેટને કોડ ફેરફારનો ભાગ બનાવી રહ્યો છું.