ਦਸਤਾਵੇਜ਼, README ਅਤੇ ਕੋਡ ਟਿੱਪਣੀਆਂ

ਲਾਭ:

• AI ਦੇ ਨਾਲ ਟੀਚੇ ਦੇ ਦਰਸ਼ਕਾਂ ਅਤੇ ਸਰੋਤ ਦੇ ਅਧਾਰ ਤੇ README, docstring ਅਤੇ changelog ਡਰਾਫਟ ਤਿਆਰ ਕਰਨ ਦੀ ਸਮਰੱਥਾ
• ਦਸਤਾਵੇਜ਼ਾਂ ਵਿੱਚ 'ਕੀ/ਕਿਵੇਂ' ਅਤੇ 'ਕਿਉਂ' ਲੇਅਰਾਂ ਨੂੰ ਵੱਖ ਕਰਨ ਅਤੇ ਇੱਕ ਮਨੁੱਖ ਵਜੋਂ 'ਕਿਉਂ' ਜੋੜਨ ਦੀ ਸਮਰੱਥਾ
• ਉਹਨਾਂ ਨੂੰ ਨਿੱਜੀ ਤੌਰ 'ਤੇ ਚਲਾ ਕੇ ਅਤੇ ਦਸਤਾਵੇਜ਼ ਨੂੰ ਕੋਡ ਪਰਿਵਰਤਨ ਦਾ ਹਿੱਸਾ ਬਣਾ ਕੇ ਇੰਸਟਾਲੇਸ਼ਨ ਦੇ ਪੜਾਵਾਂ ਦੀ ਪੁਸ਼ਟੀ ਕਰਨਾ

ਸੌਫਟਵੇਅਰ ਦਾ ਸਭ ਤੋਂ ਵੱਧ ਅਕਸਰ ਨਜ਼ਰਅੰਦਾਜ਼ ਕੀਤਾ ਜਾਂਦਾ ਹੈ ਪਰ ਸਭ ਤੋਂ ਲੰਬੇ ਸਮੇਂ ਤੱਕ ਚੱਲਣ ਵਾਲਾ ਹਿੱਸਾ ਦਸਤਾਵੇਜ਼ੀ ਹੈ। ਕੋਡ ਮਹੀਨਿਆਂ ਬਾਅਦ ਵੀ ਪੜ੍ਹਨਯੋਗ ਹੈ; ਜਿਸ ਨੇ ਇਸ ਨੂੰ ਲਿਖਿਆ ਸੀ ਉਹ ਖਤਮ ਹੋ ਗਿਆ ਹੈ, ਪ੍ਰਸੰਗ ਭੁੱਲ ਗਿਆ ਹੈ, ਅਤੇ ਜੋ ਲਿਖਿਆ ਗਿਆ ਸੀ ਉਹ ਹੀ ਰਹਿ ਗਿਆ ਹੈ। ਇੱਕ ਚੰਗਾ README (ਸ਼ੁਰੂਆਤੀ ਦਸਤਾਵੇਜ਼ ਜੋ ਦੱਸਦਾ ਹੈ ਕਿ ਇੱਕ ਪ੍ਰੋਜੈਕਟ ਕੀ ਹੈ ਅਤੇ ਇਸਨੂੰ ਕਿਵੇਂ ਸਥਾਪਿਤ ਕਰਨਾ ਹੈ ਅਤੇ ਇਸਨੂੰ ਕਿਵੇਂ ਚਲਾਉਣਾ ਹੈ), ਵਿਆਖਿਆਤਮਕ ਕੋਡ ਟਿੱਪਣੀਆਂ ਅਤੇ ਇੱਕ ਅੱਪ-ਟੂ-ਡੇਟ API ਦਸਤਾਵੇਜ਼ (ਇੱਕ ਹਵਾਲਾ ਜੋ ਦੱਸਦਾ ਹੈ ਕਿ ਇੱਕ ਇੰਟਰਫੇਸ ਦੀ ਵਰਤੋਂ ਕਿਵੇਂ ਕਰਨੀ ਹੈ) ਇੱਕ ਟੀਮ ਦੀ ਗਤੀ ਨੂੰ ਸਿੱਧੇ ਤੌਰ 'ਤੇ ਨਿਰਧਾਰਤ ਕਰਦਾ ਹੈ। AI ਦਸਤਾਵੇਜ਼ਾਂ ਵਿੱਚੋਂ ਬਹੁਤ ਸਾਰੀ “ਲਿਖਣ ਦੀ ਥਕਾਵਟ” ਲੈਂਦਾ ਹੈ — ਪਰ ਇਹ ਇੱਕ ਜਾਲ ਦੇ ਨਾਲ ਆਉਂਦਾ ਹੈ: AI ਕੋਡ ਤੋਂ ਅਨੁਮਾਨ ਲਗਾ ਸਕਦਾ ਹੈ ਕਿ ਇਹ ਕੀ ਕਰਦਾ ਹੈ, ਪਰ ਅਕਸਰ ਇਹ ਨਹੀਂ ਜਾਣ ਸਕਦਾ ਕਿ ਅਜਿਹਾ ਕਿਉਂ ਕੀਤਾ ਗਿਆ ਹੈ।

ਇਸ ਯੂਨਿਟ ਵਿੱਚ, ਤੁਸੀਂ ਸਿੱਖੋਗੇ ਕਿ AI ਨਾਲ README, ਕੋਡ ਟਿੱਪਣੀ, docstring (ਟਿੱਪਣੀ ਬਲਾਕ ਪ੍ਰਤੀ ਫੰਕਸ਼ਨ/ਕਲਾਸ ਲਿਖਿਆ), API ਦਸਤਾਵੇਜ਼ ਅਤੇ ਚੇਂਜਲੌਗ ਕਿਵੇਂ ਤਿਆਰ ਕਰਨਾ ਹੈ; ਅਤੇ ਦਸਤਾਵੇਜ਼ਾਂ ਦੇ ਸਭ ਤੋਂ ਕੀਮਤੀ ਹਿੱਸੇ ਨੂੰ ਮਨੁੱਖੀ ਤੌਰ 'ਤੇ ਕਿਵੇਂ ਸੁਰੱਖਿਅਤ ਰੱਖਣਾ ਹੈ: "ਕਿਉਂ।"

"ਕੀ" ਅਤੇ "ਕਿਉਂ" ਵਿਚਕਾਰ ਅੰਤਰ

ਦਸਤਾਵੇਜ਼ਾਂ ਦੀਆਂ ਦੋ ਪਰਤਾਂ ਹਨ। ਪਹਿਲਾ ਇਹ ਹੈ ਕਿ ਕੀ/ਕਿਵੇਂ: "ਇਹ ਫੰਕਸ਼ਨ ਇੱਕ ਸੂਚੀ ਨੂੰ ਕ੍ਰਮਬੱਧ ਕਰਦਾ ਹੈ", "ਇੰਸਟਾਲ ਕਰਨ ਲਈ ਇਹ ਕਮਾਂਡ ਚਲਾਓ"। ਇਹਨਾਂ ਨੂੰ ਕੋਡ ਅਤੇ ਬਣਤਰ ਤੋਂ ਕੱਢਿਆ ਜਾ ਸਕਦਾ ਹੈ; ਏਆਈ ਇੱਥੇ ਉੱਤਮ ਹੈ। ਦੂਜਾ, ਕਿਉਂ: "ਅਸੀਂ ਇਸ ਸੇਵਾ ਨੂੰ ਸਮਕਾਲੀ ਦੀ ਬਜਾਏ ਅਸਿੰਕਰੋਨਸ ਕਿਉਂ ਬਣਾਇਆ", "ਇਹ ਸੀਮਾ ਮੁੱਲ 30 ਸਕਿੰਟ ਕਿਉਂ ਹੈ", "ਅਸੀਂ ਇਸ ਲਾਇਬ੍ਰੇਰੀ ਨੂੰ ਦੂਜੇ ਨਾਲੋਂ ਕਿਉਂ ਚੁਣਿਆ"। ਇਹ ਕੋਡ ਵਿੱਚ ਨਹੀਂ ਲਿਖੇ ਗਏ ਹਨ; ਇਹ ਡਿਜ਼ਾਈਨ ਫੈਸਲਿਆਂ, ਰੁਕਾਵਟਾਂ ਅਤੇ ਪਿਛਲੇ ਦਰਦ ਦਾ ਉਤਪਾਦ ਹੈ.

AI ਨਹੀਂ ਜਾਣਦਾ "ਕਿਉਂ"; ਸਭ ਤੋਂ ਵਧੀਆ, ਇਹ ਇੱਕ ਵਾਜਬ ਅਨੁਮਾਨ ਬਣਾਉਂਦਾ ਹੈ - ਜੋ ਕਿ ਖ਼ਤਰਨਾਕ ਹੈ, ਕਿਉਂਕਿ ਇੱਕ ਗਲਤ ਕਾਰਨ ਬਿਨਾਂ ਕਿਸੇ ਕਾਰਨ ਨਾਲੋਂ ਵੀ ਮਾੜਾ ਹੁੰਦਾ ਹੈ। ਇਸ ਲਈ ਕਿਰਤ ਦੀ ਵੰਡ ਸਪੱਸ਼ਟ ਹੈ: AI "ਕੀ/ਕਿਵੇਂ" ਦਾ ਖਰੜਾ ਤਿਆਰ ਕਰਦਾ ਹੈ, ਤੁਸੀਂ "ਕਿਉਂ" ਜੋੜਦੇ ਹੋ। ਸਭ ਤੋਂ ਕੀਮਤੀ ਟਿੱਪਣੀ ਉਹ ਹੈ ਜੋ ਕਹਿੰਦੀ ਹੈ ਕਿ ਕੋਡ ਕੀ ਨਹੀਂ ਕਹਿ ਸਕਦਾ.

ਨੁਕਤਾ: ਇੱਕ ਟਿੱਪਣੀ ਦੇ ਨਾਲ ਨਾ ਦੁਹਰਾਓ ਜੋ ਕੋਡ ਆਪਣੇ ਆਪ ਵਿੱਚ ਸਪਸ਼ਟ ਤੌਰ 'ਤੇ ਕਹਿੰਦਾ ਹੈ (ਜਿਵੇਂ i = i + 1 // i ਨੂੰ ਇੱਕ ਕਰਕੇ ਵਧਾਓ)। AI ਕਈ ਵਾਰ ਅਜਿਹੀਆਂ ਬੇਲੋੜੀਆਂ ਟਿੱਪਣੀਆਂ ਪੈਦਾ ਕਰਦਾ ਹੈ; ਉਹਨਾਂ ਨੂੰ ਖਤਮ ਕਰੋ ਅਤੇ "ਕਿਉਂ" ਟਿੱਪਣੀਆਂ ਲਈ ਆਪਣੀ ਊਰਜਾ ਸਮਰਪਿਤ ਕਰੋ।

ਕਦਮ-ਦਰ-ਕਦਮ: ਏਆਈ ਦੇ ਨਾਲ ਦਸਤਾਵੇਜ਼ ਬਣਾਉਣਾ

1. ਨਿਸ਼ਾਨਾ ਦਰਸ਼ਕ ਨਿਰਧਾਰਤ ਕਰੋ। “ਇੱਕ ਡਿਵੈਲਪਰ ਹੁਣੇ ਸ਼ੁਰੂ ਹੋ ਰਿਹਾ ਹੈ,” “ਬਾਹਰੀ ਟੀਮ ਜੋ ਇਸ API ਦੀ ਵਰਤੋਂ ਕਰੇਗੀ,” “ਭਵਿੱਖ ਵਿੱਚ ਮੈਂ” — ਦਰਸ਼ਕ ਭਾਸ਼ਾ ਅਤੇ ਡੂੰਘਾਈ ਲਈ ਟੋਨ ਸੈੱਟ ਕਰਦੇ ਹਨ।
2. ਸਰੋਤ ਦਿਓ. ਪ੍ਰੋਂਪਟ ਵਿੱਚ ਸੰਬੰਧਿਤ ਕੋਡ, ਮੌਜੂਦਾ README, ਉਦਾਹਰਨ ਵਰਤੋਂ ਸ਼ਾਮਲ ਕਰੋ। ਇੱਕ ਅਨਸੋਰਸਡ ਦਸਤਾਵੇਜ਼ ਬਨਾਵਟੀ ਲਈ ਇੱਕ ਸੱਦਾ ਹੈ।
3. ਲਾਗੂ ਕਰਨ ਦੀ ਬਣਤਰ. README ਲਈ ਮਿਆਰੀ ਭਾਗ (ਉਦੇਸ਼, ਸਥਾਪਨਾ, ਵਰਤੋਂ, ਸੰਰਚਨਾ, ਯੋਗਦਾਨ), docstring ਲਈ ਪ੍ਰੋਜੈਕਟ ਫਾਰਮੈਟ।
4. "ਕਿਉਂ" ਸਪੇਸ ਨੂੰ ਚਿੰਨ੍ਹਿਤ ਕਰੋ। AI ਨੂੰ ਉਹਨਾਂ ਫੈਸਲਿਆਂ ਦੀ ਨਿਸ਼ਾਨਦੇਹੀ ਕਰਨ ਲਈ ਕਹੋ ਜਿਹਨਾਂ ਲਈ ਇਹ "ਇੱਥੇ 'ਕਿਉਂ' ਨੋਟ ਦੀ ਲੋੜ ਹੈ" ਦੇ ਤਰਕ ਨੂੰ ਨਹੀਂ ਜਾਣਦਾ ਹੈ; ਫਿਰ ਤੁਸੀਂ ਉਹਨਾਂ ਖਾਲੀ ਥਾਂਵਾਂ ਨੂੰ ਭਰੋ।
5. ਪੁਸ਼ਟੀ ਕਰੋ। ਅਸਲ ਵਿੱਚ ਇੰਸਟਾਲੇਸ਼ਨ ਕਦਮ ਚਲਾਓ; ਨਮੂਨਾ ਕੋਡ ਦੀ ਕੋਸ਼ਿਸ਼ ਕਰੋ. ਇੱਕ README ਜੋ ਕੰਮ ਨਹੀਂ ਕਰਦਾ, ਕਿਸੇ ਵੀ README ਤੋਂ ਵੀ ਮਾੜਾ ਹੁੰਦਾ ਹੈ।

ਤਿੰਨ ਮਿੰਨੀ ਕੇਸ

ਕੇਸ 1 — README ਨੇ ਆਨਬੋਰਡਿੰਗ ਨੂੰ ਤੇਜ਼ ਕੀਤਾ। ਇੱਕ ਓਪਨ ਸੋਰਸ ਟੂਲ ਦਾ README ਗੁੰਮ ਸੀ; ਨਵੇਂ ਯੋਗਦਾਨੀਆਂ ਨੇ ਔਸਤਨ 2 ਘੰਟਿਆਂ ਲਈ ਸਥਾਪਨਾ ਨਾਲ ਸੰਘਰਸ਼ ਕੀਤਾ। ਟੀਮ ਨੇ AI ਨੂੰ ਇੰਸਟਾਲੇਸ਼ਨ ਸਕ੍ਰਿਪਟਾਂ ਅਤੇ package.json ਦਿੱਤੀਆਂ ਅਤੇ ਇੱਕ ਸਟ੍ਰਕਚਰਡ README ਦਾ ਖਰੜਾ ਤਿਆਰ ਕੀਤਾ, ਫਿਰ ਇੱਕ ਸਾਫ਼ ਮਸ਼ੀਨ 'ਤੇ ਆਪਣੇ ਆਪ ਕਦਮਾਂ ਨੂੰ ਚਲਾਇਆ ਅਤੇ ਦੋ ਗੁੰਮ ਹੋਈਆਂ ਨਿਰਭਰਤਾਵਾਂ ਨੂੰ ਜੋੜਿਆ। ਬਾਅਦ ਦੇ ਯੋਗਦਾਨੀਆਂ ਲਈ ਸਥਾਪਨਾ ਦਾ ਸਮਾਂ ਔਸਤਨ 25 ਮਿੰਟ ਤੱਕ ਘਟ ਗਿਆ।

ਕੇਸ 2 - ਬਣਾਇਆ ਗਿਆ "ਕਿਉਂ" ਜਾਲ। ਇੱਕ ਡਿਵੈਲਪਰ ਨੇ AI ਨੂੰ ਇੱਕ ਟਾਈਮਆਉਟ ਮੁੱਲ (ਟਾਈਮਆਉਟ=30) ਦੇ ਅੱਗੇ ਇੱਕ ਟਿੱਪਣੀ ਲਈ ਕਿਹਾ। ਏਆਈ ਨੇ "ਉੱਚ ਨੈੱਟਵਰਕ ਲੇਟੈਂਸੀ ਨੂੰ ਬਰਦਾਸ਼ਤ ਕਰਨ ਲਈ" ਇੱਕ ਵਾਜਬ ਪਰ ਗਲਤ ਤਰਕਸੰਗਤ ਲਿਖਿਆ; ਅਸਲ ਕਾਰਨ ਇੱਕ ਡਾਊਨਸਟ੍ਰੀਮ ਸੇਵਾ ਦੀ ਇਕਰਾਰਨਾਮੇ ਦੀ 30-ਸਕਿੰਟ ਦੀ ਸੀਮਾ ਸੀ। ਗਲਤ ਵਿਆਖਿਆ ਨੇ ਬਾਅਦ ਦੇ ਡਿਵੈਲਪਰ ਨੂੰ ਬੇਲੋੜੇ ਮੁੱਲ ਨੂੰ ਵਧਾਉਣ ਲਈ ਅਗਵਾਈ ਕੀਤੀ, ਜਿਸ ਨਾਲ ਇੱਕ ਘਟਨਾ ਵਾਪਰੀ। ਪਾਠ: ਕੋਡ ਦੇ ਮਾਲਕ ਨੂੰ ਜਾਇਜ਼ਤਾ ਦੀ ਪੁਸ਼ਟੀ ਕਰਨੀ ਚਾਹੀਦੀ ਹੈ।

ਕੇਸ 3 - Docstring ਸਟੈਂਡਰਡ ਸਵੈਚਲਿਤ ਹੋ ਗਿਆ ਹੈ। 40 ਫੰਕਸ਼ਨਾਂ ਵਾਲੇ ਇੱਕ ਸਹਾਇਕ ਮੋਡੀਊਲ ਵਿੱਚ ਕੋਈ ਡੌਕਸਟ੍ਰਿੰਗ ਨਹੀਂ ਸੀ। AI ਨੂੰ ਪ੍ਰੋਜੈਕਟ ਫਾਰਮੈਟ (ਗੂਗਲ ਸਟਾਈਲ) ਦਿੱਤਾ ਗਿਆ ਸੀ ਅਤੇ ਹਰੇਕ ਫੰਕਸ਼ਨ ਲਈ ਪੈਰਾਮੀਟਰ, ਵਾਪਸੀ ਅਤੇ ਅਪਵਾਦ ਵਰਣਨ ਤਿਆਰ ਕੀਤਾ ਗਿਆ ਸੀ; ਡਿਵੈਲਪਰ ਨੇ ਇਹਨਾਂ ਦੀ ਸਮੀਖਿਆ ਕੀਤੀ ਅਤੇ ਕੁਝ ਗਲਤ ਕਿਸਮ ਦੇ ਘੋਸ਼ਣਾਵਾਂ ਨੂੰ ਠੀਕ ਕੀਤਾ। 40 ਫੰਕਸ਼ਨਾਂ ਦਾ ਦਸਤਾਵੇਜ਼ੀਕਰਨ ਅੱਧੇ ਦਿਨ ਤੋਂ ਘਟ ਕੇ ਇੱਕ ਘੰਟੇ ਤੱਕ ਚਲਾ ਗਿਆ।

ਚਾਰ ਕਾਪੀ ਕਰਨ ਯੋਗ ਨਮੂਨੇ

ਸਟ੍ਰਕਚਰਡ README ਡਰਾਫਟ:

ਟੀਚਾ ਦਰਸ਼ਕ: {{ਉਦਾ. new contributor}}. ਹੇਠਾਂ ਦਿੱਤੀਆਂ ਫਾਈਲਾਂ ਦੇ ਅਧਾਰ ਤੇ ਇੱਕ ਡਰਾਫਟ README ਲਿਖੋ। ਭਾਗ: ਉਦੇਸ਼, ਵਿਸ਼ੇਸ਼ਤਾਵਾਂ, ਲੋੜਾਂ, ਸਥਾਪਨਾ, ਸੰਚਾਲਨ, ਸੰਰਚਨਾ, ਟੈਸਟਿੰਗ, ਯੋਗਦਾਨ। ਅਸਲ ਫਾਈਲਾਂ ਤੋਂ ਇੰਸਟਾਲੇਸ਼ਨ/ਰਨਿੰਗ ਕਮਾਂਡਾਂ ਨੂੰ ਐਕਸਟਰੈਕਟ ਕਰੋ; ਫਿਟਿੰਗ। ਉਹਨਾਂ ਥਾਵਾਂ 'ਤੇ ਨਿਸ਼ਾਨ ਲਗਾਓ ਜਿਨ੍ਹਾਂ ਬਾਰੇ ਤੁਸੀਂ ਯਕੀਨੀ ਨਹੀਂ ਹੋ "[VERIFY]" ਨਾਲ। ਸਰੋਤ: {{package.json/scripts/sample code}}

Docstring/API ਹਵਾਲਾ:

ਇਹਨਾਂ ਫੰਕਸ਼ਨਾਂ ਲਈ docstring {{project style: Google/NumPy/JSDoc}} ਫਾਰਮੈਟ ਵਿੱਚ ਲਿਖੋ: ਛੋਟਾ ਸੰਖੇਪ, ਪੈਰਾਮੀਟਰ (ਕਿਸਮ + ਅਰਥ), ਵਾਪਸੀ, ਅਪਵਾਦ ਸੁੱਟੇ ਗਏ, 1 ਛੋਟੀ ਉਦਾਹਰਨ। ਜੋ ਕੋਡ ਸਪੱਸ਼ਟ ਤੌਰ 'ਤੇ ਕਹਿੰਦਾ ਹੈ, ਉਸ ਨੂੰ ਨਾ ਦੁਹਰਾਓ। ਡਿਜ਼ਾਈਨ ਫੈਸਲਿਆਂ ਦੀ ਨਿਸ਼ਾਨਦੇਹੀ ਕਰੋ ਜਿਨ੍ਹਾਂ ਲਈ "ਕਿਉਂ" ਦੀ ਲੋੜ ਹੁੰਦੀ ਹੈ "[WHY NECESSARY]", ਇੱਕ ਮਨਘੜਤ ਤਰਕਸੰਗਤ ਨਾ ਲਿਖੋ।{{code}}

"ਕਿਉਂ" ਟਿੱਪਣੀ ਲਈ ਸਪੇਸ ਹਟਾਓ:

ਇਸ ਕੋਡ ਵਿੱਚ, ਅਗਲਾ ਵਿਕਾਸਕਾਰ ਪੁੱਛ ਸਕਦਾ ਹੈ "ਇਹ ਅਜਿਹਾ ਕਿਉਂ ਹੈ?" (ਜਾਦੂ ਦੀ ਸੰਖਿਆ, ਅਸਧਾਰਨ ਫੈਸਲੇ, ਹੱਲ)। ਹਰੇਕ ਲਈ ਇੱਕ ਟਿੱਪਣੀ SKELETON ਦਿਓ, ਪਰ ਤਰਕ ਨੂੰ ਖਾਲੀ ਛੱਡ ਦਿਓ; ਮੈਂ ਜਾਇਜ਼ਤਾ ਭਰਾਂਗਾ।{{code}}

ਚੇਂਜਲੌਗ/PR ਸਟੇਟਮੈਂਟ:

ਹੇਠਾਂ ਦਿੱਤੇ ਅੰਤਰ ਤੋਂ ਇੱਕ {{ਚੇਂਜਲਾਗ ਐਂਟਰੀ / PR ਵਰਣਨ}} ਲਿਖੋ। ਫਾਰਮੈਟ: ਕੀ ਬਦਲਿਆ (ਉਪਭੋਗਤਾ ਭਾਸ਼ਾ ਵਿੱਚ), ਕਿਉਂ (ਮਸਲਾ: {{...}}), ਤੋੜਨ ਵਾਲੀ ਤਬਦੀਲੀ (ਜੇ ਕੋਈ ਹੈ), ਕੀ ਇਸਦੀ ਜਾਂਚ ਕੀਤੀ ਗਈ ਹੈ। ਟੀਚਾ ਦਰਸ਼ਕ ਲਈ ਤਕਨੀਕੀ ਸ਼ਬਦਾਵਲੀ ਵਿਵਸਥਿਤ ਕਰੋ।{{diff}}

ਕਮਜ਼ੋਰ ਪ੍ਰੋਂਪਟ / ਮਜ਼ਬੂਤ ਪ੍ਰੋਂਪਟ

ਕਮਜ਼ੋਰ: "ਇਸ ਪ੍ਰੋਜੈਕਟ ਲਈ ਇੱਕ README ਲਿਖੋ।"

ਮਜ਼ਬੂਤ: "ਨਿਸ਼ਾਨਾ ਦਰਸ਼ਕ: ਇੱਕ ਡਿਵੈਲਪਰ ਪਹਿਲੀ ਵਾਰ ਇਸ ਰੈਪੋ ਨੂੰ ਕਲੋਨ ਕਰ ਰਿਹਾ ਹੈ। ਨੱਥੀ ਪੈਕੇਜ.json, docker-compose.yml ਅਤੇ ਸਕ੍ਰਿਪਟਾਂ/ ਫੋਲਡਰ ਦੇ ਅਧਾਰ ਤੇ, ਉਦੇਸ਼, ਲੋੜਾਂ, ਸਥਾਪਨਾ, ਸੰਚਾਲਨ, ਟੈਸਟਿੰਗ, ਯੋਗਦਾਨ ਸੈਕਸ਼ਨਾਂ ਦੇ ਨਾਲ ਇੱਕ ਡਰਾਫਟ README ਲਿਖੋ। ਇਹਨਾਂ ਫਾਈਲਾਂ ਤੋਂ ਕਮਾਂਡਾਂ ਨੂੰ ਐਕਸਟਰੈਕਟ ਕਰੋ, ਇਹ ਯਕੀਨੀ ਬਣਾਓ ਕਿ ਤੁਸੀਂ ਇਹਨਾਂ ਫਾਈਲਾਂ ਨਾਲ ਮਾਰਕ ਨਾ ਕਰੋ; [ਪੁਸ਼ਟੀ ਕਰੋ]।"

ਮਜ਼ਬੂਤ ​​ਸੰਸਕਰਣ ਦਰਸ਼ਕਾਂ ਨੂੰ, ਸਰੋਤ, ਬਣਤਰ, ਅਤੇ "ਇਸ ਨੂੰ ਬਣਾਓ, ਇਸ ਨੂੰ ਮਾਰਕ ਕਰੋ" ਨਿਯਮ ਦਿੰਦਾ ਹੈ; ਤਾਂ ਜੋ ਦਸਤਾਵੇਜ਼ ਅਸਲ ਫਾਈਲਾਂ 'ਤੇ ਅਧਾਰਤ ਹੋਵੇ ਅਤੇ ਤਸਦੀਕ ਕੀਤੇ ਜਾਣ ਵਾਲੇ ਸਥਾਨ ਸਪਸ਼ਟ ਤੌਰ 'ਤੇ ਦਿਖਾਈ ਦੇਣ।

ਦਸਤਾਵੇਜ਼ ਦੀ ਕਿਸਮ

AI ਚੰਗੀ ਤਰ੍ਹਾਂ ਕਰਦਾ ਹੈ

ਮਨੁੱਖ ਜੋੜਦਾ/ਪੁਸ਼ਟੀ ਕਰਦਾ ਹੈ

README ਸਥਾਪਨਾ

ਕਦਮ ਦੀ ਰੂਪਰੇਖਾ

ਕਦਮ ਚਲਾਓ ਅਤੇ ਪੁਸ਼ਟੀ ਕਰੋ

Docstring/API

ਬਣਤਰ, ਪੈਰਾਮੀਟਰ, ਕਿਸਮ

ਸਹੀ ਕਿਸਮ ਅਤੇ "ਕਿਉਂ"

ਕੋਡ ਟਿੱਪਣੀ

"ਉਹ ਕੀ ਕਰ ਰਿਹਾ ਹੈ" ਸੰਖੇਪ

"ਇਹ ਕਿਉਂ" ਜਾਇਜ਼ ਹੈ

ਚੇਂਜਲੌਗ/ਪੀ.ਆਰ

ਪਹਿਲਾ ਡਰਾਫਟ

ਪ੍ਰਭਾਵ ਅਤੇ ਸ਼ੁੱਧਤਾ

ਆਰਕੀਟੈਕਚਰਲ ਫੈਸਲਾ (ADR)

ਪਿੰਜਰ

ਅਸਲ ਫੈਸਲੇ ਅਤੇ ਸਮਝੌਤਾ

ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ ਰੱਖ-ਰਖਾਅ ਦੀ ਲੋੜ ਹੈ

ਕਿਸੇ ਦਸਤਾਵੇਜ਼ ਦਾ ਸਭ ਤੋਂ ਖ਼ਤਰਨਾਕ ਪਹਿਲੂ ਉਦੋਂ ਹੁੰਦਾ ਹੈ ਜਦੋਂ ਇਹ ਝੂਠਾ ਹੋਣ ਦੇ ਬਾਵਜੂਦ ਸਹੀ ਦਿਖਾਈ ਦਿੰਦਾ ਹੈ। ਜਦੋਂ ਕੋਡ ਬਦਲਦਾ ਹੈ ਅਤੇ ਦਸਤਾਵੇਜ਼ ਨੂੰ ਅਪਡੇਟ ਨਹੀਂ ਕੀਤਾ ਜਾਂਦਾ ਹੈ, ਤਾਂ ਇਹ ਰੀਡਰ ਨੂੰ ਸਰਗਰਮੀ ਨਾਲ ਗੁੰਮਰਾਹ ਕਰਦਾ ਹੈ। AI ਅੱਪਡੇਟ ਕਰਨਾ ਆਸਾਨ ਬਣਾਉਂਦਾ ਹੈ: ਇੱਕ ਅੰਤਰ ਜਾਰੀ ਕਰੋ ਅਤੇ ਪੁੱਛੋ "ਦਸਤਾਵੇਜ਼ ਦੇ ਕਿਹੜੇ ਭਾਗਾਂ ਨੂੰ ਇਹ ਤਬਦੀਲੀ ਪ੍ਰਭਾਵਿਤ ਕਰਦੀ ਹੈ?" ਤੁਸੀਂ ਪੁੱਛ ਸਕਦੇ ਹੋ। ਪਰ ਇਹ ਉਹ ਪ੍ਰਕਿਰਿਆ ਹੈ ਜੋ ਅੱਪ-ਟੂ-ਡੇਟ ਨੂੰ ਯਕੀਨੀ ਬਣਾਉਂਦੀ ਹੈ — ਦਸਤਾਵੇਜ਼ੀ ਅੱਪਡੇਟ ਨੂੰ ਕੋਡ ਬਦਲਾਅ (PR ਦੀ ਸਵੀਕ੍ਰਿਤੀ ਮਾਪਦੰਡ) ਦਾ ਹਿੱਸਾ ਬਣਾਓ। ਏਆਈ ਤੇਜ਼ ਕਰਦਾ ਹੈ; ਟੀਮ ਅਨੁਸ਼ਾਸਨ ਪੈਦਾ ਕਰਦੀ ਹੈ।

ਸਾਵਧਾਨ: README ਵਿੱਚ ਇੰਸਟਾਲੇਸ਼ਨ ਦੇ ਪੜਾਵਾਂ ਦੀ ਪੁਸ਼ਟੀ ਕੀਤੇ ਬਿਨਾਂ ਪ੍ਰਕਾਸ਼ਿਤ ਨਾ ਕਰੋ। ਇੱਕ "ਸ਼ਾਇਦ ਕੰਮ" ਦਸਤਾਵੇਜ਼ ਇੱਕ ਨਵੇਂ ਡਿਵੈਲਪਰ ਦੇ ਪਹਿਲੇ ਦਿਨ ਨੂੰ ਬਰਬਾਦ ਕਰ ਸਕਦਾ ਹੈ ਅਤੇ ਵਿਸ਼ਵਾਸ ਨੂੰ ਖਤਮ ਕਰ ਸਕਦਾ ਹੈ। ਇੱਕ ਸਾਫ਼ ਵਾਤਾਵਰਣ ਵਿੱਚ ਆਪਣੇ ਆਪ ਨੂੰ ਕਦਮ ਚਲਾਓ.

ਆਮ ਗਲਤੀਆਂ

• AI ਨੂੰ ਫਿੱਟ ਕਰਨ ਲਈ "ਕਿਉਂ" ਪ੍ਰਾਪਤ ਕਰਨਾ। ਝੂਠਾ ਜਾਇਜ਼ ਠਹਿਰਾਉਣਾ ਕਿਸੇ ਵੀ ਤਰਕਸੰਗਤ ਨਾਲੋਂ ਵੀ ਮਾੜਾ ਹੈ; ਕੋਡ ਦੇ ਮਾਲਕ ਨੂੰ ਡਿਜ਼ਾਈਨ ਕਾਰਨ ਲਿਖਣਾ ਚਾਹੀਦਾ ਹੈ।
• ਇੰਸਟਾਲੇਸ਼ਨ ਪੜਾਵਾਂ ਦੀ ਪੁਸ਼ਟੀ ਨਹੀਂ ਕੀਤੀ ਜਾ ਰਹੀ ਹੈ। README ਜੋ ਕੰਮ ਨਹੀਂ ਕਰਦਾ ਵਿਸ਼ਵਾਸ ਨੂੰ ਨਸ਼ਟ ਕਰਦਾ ਹੈ।
• ਕੋਡ ਨੂੰ ਦੁਹਰਾਉਣ ਵਾਲੀ ਬੇਲੋੜੀ ਟਿੱਪਣੀ। ਇਹ ਸ਼ੋਰ ਪੈਦਾ ਕਰਦਾ ਹੈ, ਅਸਲ "ਕਿਉਂ" ਵਿਆਖਿਆਵਾਂ ਨੂੰ ਅਸਪਸ਼ਟ ਕਰਦਾ ਹੈ।
• ਟੀਚਾ ਦਰਸ਼ਕ ਨਿਰਧਾਰਤ ਨਹੀਂ ਕਰ ਰਿਹਾ। ਇੱਕ ਦਸਤਾਵੇਜ਼ ਜੋ ਅਸਪਸ਼ਟ ਹੈ ਕਿ ਇਹ ਕਿਸ ਲਈ ਲਿਖਿਆ ਗਿਆ ਹੈ, ਕਿਸੇ ਨਵੇਂ ਜਾਂ ਮਾਹਰ ਲਈ ਕੋਈ ਲਾਭਦਾਇਕ ਨਹੀਂ ਹੈ.
• ਅੱਪਡੇਟ ਨੂੰ ਪ੍ਰਕਿਰਿਆ ਤੋਂ ਵੱਖ ਕਰਨਾ। ਜੇਕਰ ਦਸਤਾਵੇਜ਼ ਨੂੰ ਕੋਡ ਨਾਲ ਅੱਪਡੇਟ ਨਹੀਂ ਕੀਤਾ ਜਾਂਦਾ ਹੈ ਤਾਂ ਇਹ ਛੇਤੀ ਹੀ ਗੁੰਮਰਾਹਕੁੰਨ ਹੋ ਜਾਂਦਾ ਹੈ।

ਸੰਖੇਪ ਵਿੱਚ

AI ਦਸਤਾਵੇਜ਼ਾਂ ਤੋਂ ਬਹੁਤ ਸਾਰਾ ਮਕੈਨੀਕਲ ਬੋਝ ਲੈਂਦਾ ਹੈ: ਤੇਜ਼ ਡਰਾਫਟ README, docstring, API ਸੰਦਰਭ, ਚੇਂਜਲੌਗ ਅਤੇ PR ਵਰਣਨ। ਪਰ ਇਹ "ਕਿਉਂ" ਨਹੀਂ ਜਾਣ ਸਕਦਾ, ਜੋ ਕਿ ਸਭ ਤੋਂ ਕੀਮਤੀ ਪਰਤ ਹੈ, ਅਤੇ ਇਸਨੂੰ ਬਣਾਉਣਾ ਖਤਰਨਾਕ ਹੈ। ਕਿਰਤ ਦੀ ਵੰਡ ਸਪੱਸ਼ਟ ਹੈ: AI "ਕੀ/ਕਿਵੇਂ" ਪੈਦਾ ਕਰਦਾ ਹੈ, ਤੁਸੀਂ "ਕਿਉਂ" ਜੋੜਦੇ ਹੋ। ਦਰਸ਼ਕ ਨਿਰਧਾਰਤ ਕਰੋ, ਸਰੋਤ ਪ੍ਰਦਾਨ ਕਰੋ, ਢਾਂਚਾ ਲਗਾਓ, ਫਿੱਟ ਕਰਨ ਲਈ ਸਥਾਨਾਂ ਦੀ ਨਿਸ਼ਾਨਦੇਹੀ ਕਰੋ, ਅਤੇ ਇਸਨੂੰ ਆਪਣੇ ਆਪ ਚਲਾ ਕੇ ਹਰੇਕ ਸਥਾਪਨਾ ਪੜਾਅ ਦੀ ਪੁਸ਼ਟੀ ਕਰੋ। ਦਸਤਾਵੇਜ਼ ਨੂੰ ਕੋਡ ਤਬਦੀਲੀ ਦਾ ਇੱਕ ਅਨਿੱਖੜਵਾਂ ਅੰਗ ਬਣਾਓ।

ਐਪਲੀਕੇਸ਼ਨ ਦਾ ਕੰਮ

ਇੱਕ ਮਾਡਿਊਲ ਜਾਂ ਛੋਟਾ ਪ੍ਰੋਜੈਕਟ ਚੁਣੋ ਜਿਸਦਾ ਦਸਤਾਵੇਜ਼ ਗੁੰਮ ਹੈ ਜਾਂ ਪੁਰਾਣਾ ਹੈ। ਪਹਿਲਾਂ AI ਤੋਂ “ਸਟ੍ਰਕਚਰਡ README ਡਰਾਫਟ” (ਜਾਂ docstring) ਟੈਂਪਲੇਟ ਨਾਲ ਇੱਕ ਰੂਪਰੇਖਾ ਤਿਆਰ ਕਰੋ; ਸਰੋਤ ਅਤੇ ਨਿਸ਼ਾਨਾ ਦਰਸ਼ਕਾਂ ਨੂੰ ਦੇਣਾ ਯਕੀਨੀ ਬਣਾਓ। ਫਿਰ ਹਰੇਕ ਬਿੰਦੂ 'ਤੇ ਜਾਓ ਜਿੱਥੇ AI ਨੇ [ਵੇਰੀਫਾਈ] ਜਾਂ [ਕਿਉਂ ਲੋੜੀਂਦਾ] ਮਾਰਕ ਕੀਤਾ ਹੈ: ਅਸਲ ਵਿੱਚ ਸੈੱਟਅੱਪ ਸਟੈਪਸ ਚਲਾਓ ਅਤੇ ਆਪਣੇ ਖੁਦ ਦੇ ਗਿਆਨ ਨਾਲ ਡਿਜ਼ਾਈਨ "ਕਿਉਂ" ਭਰੋ। ਨੋਟ ਕਰੋ ਕਿ ਕਿੰਨੇ ਕਦਮਾਂ ਨੂੰ ਠੀਕ ਕਰਨ ਦੀ ਲੋੜ ਹੈ ਅਤੇ ਤੁਸੀਂ ਕਿੰਨੇ "ਕਿਉਂ" ਸ਼ਾਮਲ ਕੀਤੇ ਹਨ।

ਚੈੱਕਲਿਸਟ

• [ ] ਦਸਤਾਵੇਜ਼ ਵਿੱਚ, ਮੈਂ "ਕੀ/ਕਿਵੇਂ" ਅਤੇ "ਕਿਉਂ" ਲੇਅਰਾਂ ਵਿੱਚ ਫਰਕ ਕਰਦਾ ਹਾਂ।
• [ ] ਮੈਂ AI ਨੂੰ "ਕਿਉਂ" ਨਹੀਂ ਬਣਾਉਂਦਾ, ਮੈਂ ਇਸਨੂੰ ਆਪਣੇ ਆਪ ਜੋੜਦਾ ਹਾਂ।
• [ ] ਮੈਂ ਪ੍ਰੋਂਪਟ ਨੂੰ ਨਿਸ਼ਾਨਾ ਦਰਸ਼ਕ ਅਤੇ ਅਸਲ ਸਰੋਤ ਫਾਈਲਾਂ ਦਿੰਦਾ ਹਾਂ।
• [ ] ਮੈਂ AI ਦੁਆਰਾ ਚਿੰਨ੍ਹਿਤ [ VERIFY ] ਪੁਆਇੰਟਾਂ ਨੂੰ ਨਿੱਜੀ ਤੌਰ 'ਤੇ ਲਾਗੂ ਕਰਕੇ ਪੁਸ਼ਟੀ ਕਰਦਾ ਹਾਂ।
• [ ] ਮੈਂ ਬੇਲੋੜੀਆਂ ਟਿੱਪਣੀਆਂ ਨੂੰ ਖਤਮ ਕਰਦਾ ਹਾਂ ਜੋ ਕੋਡ ਨੂੰ ਦੁਹਰਾਉਂਦੇ ਹਨ।
• [ ] ਮੈਂ ਦਸਤਾਵੇਜ਼ੀ ਅੱਪਡੇਟ ਨੂੰ ਕੋਡ ਤਬਦੀਲੀ ਦਾ ਹਿੱਸਾ ਬਣਾ ਰਿਹਾ ਹਾਂ।