26 ਦਸੰ 2025·8 ਮਿੰਟ
Claude Code ਲਈ ਦਸਤਾਵੇਜ਼ ਡਰਿਫਟ: README, API ਅਤੇ ਰਨਬੁੱਕ ਨੂੰ ਕੋਡ ਨਾਲ ਮਿਲਾਓ
Claude Code ਨਾਲ documentation drift ਨੂੰ ਰੋਕੋ: README, API docs ਅਤੇ runbooks ਨੂੰ ਕੋਡ ਦੇ ਅਨੁਕੂਲ ਰੱਖਣ ਲਈ diffs ਬਣਾਓ ਤੇ ਵਿਰੋਧ ਚਿੰਨ੍ਹਾਂ ਦੱਸੋ।
Claude Code ਨਾਲ documentation drift ਨੂੰ ਰੋਕੋ: README, API docs ਅਤੇ runbooks ਨੂੰ ਕੋਡ ਦੇ ਅਨੁਕੂਲ ਰੱਖਣ ਲਈ diffs ਬਣਾਓ ਤੇ ਵਿਰੋਧ ਚਿੰਨ੍ਹਾਂ ਦੱਸੋ।
ਦਸਤਾਵੇਜ਼ ਡਰਿਫਟ ਉਹ ਹੌਲੀ ਜਿਹੀ ਵੱਖਰਾ ਹੋਣਾ ਹੈ ਜਿੱਥੇ ਤੁਹਾਡੇ docs ਜੋ ਕਹਿੰਦੇ ਹਨ ਅਤੇ ਜੋ ਤੁਹਾਡਾ ਕੋਡ ਅਸਲ ਵਿੱਚ ਕਰਦਾ ਹੈ, ਉਹ ਇੱਕ-ਦੂਜੇ ਤੋਂ ਹਟ ਜਾਂਦੇ ਹਨ। ਇਹ ਛੋਟੇ-ਛੋਟੇ ਅੰਤਰਾਂ ਨਾਲ ਸ਼ੁਰੂ ਹੁੰਦਾ ਹੈ, ਫਿਰ ਉਹ "ਅਸੀਂ ਕਹਿੰਦੇ ਸੀ ਇਹ ਪਿਛਲੇ ਮਹੀਨੇ ਚੱਲਦਾ ਸੀ" ਵਾਲੀ ਗੁੰਝਲਦਾਰ ਸਥਿਤੀ ਬਣ ਜਾਂਦੀ ਹੈ।
ਅਸਲ ਟੀਮ ਵਿੱਚ, ਡਰਿਫਟ ਐਸਾ ਦਿਖਦਾ ਹੈ: README ਦੱਸਦਾ ਹੈ ਕਿ ਇੱਕ ਕਮਾਂਡ ਨਾਲ ਸੇਵਾ ਚਲਾਉਣੀ ਹੈ, ਪਰ ਹੁਣ ਇੱਕ ਨਵਾਂ environment variable ਲਾਜ਼ਮੀ ਹੋ ਗਿਆ ਹੈ। API docs ਇੱਕ ਐਂਡਪਾਇੰਟ ਵਿੱਚ ਇੱਕ ਫੀਲਡ ਦਿਖਾਉਂਦੇ ਹਨ ਜਿਸ ਦਾ ਨਾਂ ਬਦਲ ਚੁੱਕਾ ਹੈ। ਇੱਕ runbook on-call ਨੂੰ "worker-a" ਨੂੰ restart ਕਰਨ ਲਈ ਕਹਿੰਦਾ ਹੈ, ਪਰ ਹੁਣ ਉਹ ਪ੍ਰੋਸੈਸ ਦੋ ਸਰਵਿਸਾਂ ਵਿੱਚ ਵੰਡਿਆ ਗਿਆ ਹੈ।
ਡਰਿਫਟ ਵਧਦਾ ਹੈ ਭਾਵੇਂ ਇਰਾਦੇ ਚੰਗੇ ਹੋਣ, ਕਿਉਂਕਿ ਸਾਫਟਵੇਅਰ ਦਸਤਾਵੇਜ਼ੀ ਆਦਤਾਂ ਤੋਂ ਤੇਜ਼ੀ ਨਾਲ ਬਦਲਦਾ ਹੈ। ਲੋਕ ਦਬਾਅ ਹੇਠਾਂ ਫਿਕਸ ਸ਼ਿਪ ਕਰਦੇ ਹਨ, ਪੁਰਾਣੇ ਉਦਾਹਰਣਾਂ ਨੂੰ ਕਾਪੀ ਕਰ ਲੈਂਦੇ ਹਨ, ਜਾਂ ਸੋਚਦੇ ਹਨ ਕਿ ਕੋਈ ਹੋਰ ਬਾਅਦ ਵਿੱਚ docs ਅਪਡੇਟ ਕਰੇਗਾ। ਇਹ ਉਸ ਵੇਲੇ ਵੀ ਵਧਦਾ ਹੈ ਜਦੋਂ ਤੁਹਾਡੇ ਕੋਲ ਬਹੁਤ ਸਾਰੇ "source of truth" ਜਗ੍ਹਾਂ ਹੁੰਦੀਆਂ ਹਨ: README ਫਾਇਲਾਂ, API references, ਅੰਦਰੂਨੀ wiki ਪੇਜ, ਟਿਕਟ, ਅਤੇ tribal knowledge.
ਲਾਗਤਾਂ ਸਾਫ਼-ਸੁਥਰੀਆਂ ਹਨ:
ਸਿਰਫ਼ ਲਿਖਤ ਸੁਧਾਰ ਕਰਕੇ ਡਰਿਫਟ ਸੁਧਰਦਾ ਨਹੀਂ ਜੇ ਤੱਥ ਗਲਤ ਹਨ। ਮਦਦ ਇਹ ਹੁੰਦੀ ਹੈ ਕਿ docs ਨੂੰ ਇਸ ਤਰ੍ਹਾਂ ਵਰਤੋਂ ਜੋ ਤੁਸੀਂ ਵੈਰੀਫਾਈ ਕਰ ਸਕੋ: ਉਨ੍ਹਾਂ ਨੂੰ ਮੌਜੂਦਾ ਕੋਡ, configs, ਅਤੇ ਅਸਲੀ ਆਉਟਪੁੱਟ ਨਾਲ ਤੁਲਨਾ ਕਰੋ, ਫਿਰ ਜਿੱਥੇ ਦਸਤਾਵੇਜ਼ ਉਹ ਵਰਤਿਆ ਰਵੱਈਆ ਵਾਅਦਾ ਕਰਦਾ ਹੈ ਜੋ ਕੋਡ ਹੁਣ ਨਹੀਂ ਕਰਦਾ, ਉਥੇ ਵਿਰੋਧ ਦਿਖਾਓ।
ਡਰਿਫਟ ਆਮ ਤੌਰ 'ਤੇ ਉਹਨਾਂ ਦਸਤਾਵੇਜ਼ਾਂ ਵਿੱਚ ਹੁੰਦੀ ਹੈ ਜੋ ਲੋਕ "Quick reference" ਵਾਂਗ ਸੌਂਝਦੇ ਹਨ। ਇਹ ਇਕ ਵਾਰੀ ਅਪਡੇਟ ਹੋ ਜਾਂਦੇ ਹਨ, ਫਿਰ ਕੋਡ ਅੱਗੇ ਵੱਧਦਾ ਰਹਿੰਦਾ ਹੈ। ਇਨ੍ਹਾਂ ਤਿੰਨ ਤੋਂ ਸ਼ੁਰੂ ਕਰੋ ਕਿਉਂਕਿ ਇਹਨਾਂ ਵਿੱਚ ਠੋਸ ਦਾਅਵੇ ਹੁੰਦੇ ਹਨ ਜੋ ਤੁਸੀਂ ਚੈੱਕ ਕਰ ਸਕਦੇ ਹੋ।
READMEs ਉਦਾਹਰਣ ਦੌਰਾਨ ਬਦਲਣ ਵਾਲੀਆਂ ਕਮਾਂਡਾਂ ਦੇ ਨਾਲ ਡਰਿਫਟ ਕਰਦੇ ਹਨ। ਇੱਕ ਨਵਾਂ flag ਐਡ ਹੋ ਜਾਂਦਾ ਹੈ, ਇੱਕ ਪੁਰਾਣਾ ਹਟਿਆ ਜਾਂਦਾ ਹੈ, ਜਾਂ ਕੋਈ environment variable renaм ਹੋ ਜਾਂਦਾ ਹੈ, ਪਰ setup ਸੈਕਸ਼ਨ ਹਾਲੇ ਵੀ ਪੁਰਾਣੇ ਹਾਲਤ ਨੂੰ ਦਿਖਾਂਦਾ ਹੈ। ਨਵੇਂ ਸਾਥੀ README ਤੋਂ ਕਾਪੀ-ਪੇਸਟ ਕਰਦੇ ਹਨ, errors ਆਉਂਦੇ ਹਨ, ਅਤੇ ਸਮਝਦੇ ਹਨ ਕਿ ਪ੍ਰੋਜੈਕਟ ਬਿਗੜਿਆ ਹੋਇਆ ਹੈ।
ਸਭ ਤੋਂ ਬੁਰੀ ਸਥਿਤੀ "ਲਗਭਗ ਸਹੀ" ਹੈ। ਇੱਕ ਘੱਟ-ਰਹਿਆ environment variable ਇੱਕ ਪੂਰੀ ਤਰ੍ਹਾਂ outdated README ਨਾਲੋਂ ਜ਼ਿਆਦਾ ਸਮਾਂ ਬਰਬਾਦ ਕਰ ਸਕਦਾ ਹੈ, ਕਿਉਂਕਿ ਲੋਕ ਛੋਟੇ ਛੋਟੇ variations ਨੂੰ ਦੁਹਰਾ ਕੇ ਹੱਲ ਲੱਭਦੇ ਰਹਿੰਦੇ ਹਨ ਅਤੇ ਡਾਕ ਨੂੰ ਚੈਲੰਜ ਨਹੀਂ ਕਰਦੇ।
API docs ਉਨ੍ਹਾਂ ਸਥਿਤੀਆਂ ਵਿੱਚ ਡਰਿਫਟ ਹੁੰਦੇ ਹਨ ਜਦੋਂ request ਜਾਂ response ਫੀਲਡ ਬਦਲ ਜਾਂਦੇ ਹਨ। ਛੋਟੀ-ਛੋਟੀ ਤਬਦੀਲੀਆਂ (ਨਵੇਂ ਨਾਂ, defaults ਵਿੱਚ ਫਰਕ, ਨਵੀਂ ਲੋੜੀਂਦੀ headers) ਵੀ clients ਨੂੰ ਤੋੜ ਸਕਦੀਆਂ ਹਨ। ਅਕਸਰ endpoint ਸੂਚੀ ਸਹੀ ਹੁੰਦੀ ਹੈ ਪਰ ਉਦਾਹਰਣ ਗਲਤ ਹੁੰਦੇ ਹਨ, ਜੋ ਯੂਜ਼ਰ ਕਾਪੀ ਕਰਦੇ ਹਨ।
ਆਮ ਸਿਗਨਲ:
Runbooks ਉਦਾਹਰਣ ਦੇ ਰੂਪ ਵਿੱਚ ਡਰਿਫਟ ਹੁੰਦੇ ਹਨ ਜਦੋਂ deployment, rollback, ਜਾਂ operational ਕਦਮ ਬਦਲ ਜਾਂਦੇ ਹਨ। ਇੱਕ outdated ਕਮਾਂਡ, ਗਲਤ ਸਰਵਿਸ ਨਾਂ, ਜਾਂ ਘੱਟ-ਪੂਰਕ prerequisite ਇੱਕ routine fix ਨੂੰ downtime ਵਿੱਚ ਬਦਲ ਸਕਦਾ ਹੈ।
ਉਹ "ਸਹੀ ਪਰ ਅਧੂਰੇ" ਵੀ ਹੋ ਸਕਦੇ ਹਨ: ਕਦਮ ਅਜੇ ਵੀ ਕੰਮ ਕਰਦੇ ਹਨ, ਪਰ ਉਹ ਇੱਕ ਨਵੀਂ migration, cache clear, ਜਾਂ feature flag toggle ਨੂੰ ਛੱਡ ਦਿੰਦੇ ਹਨ। ਇਸ ਵੇਲੇ responders runbook ਨੂੰ ਬੇਹੱਦ ਸਹੀ ਤਰੀਕੇ ਨਾਲ ਫੋਲੋ ਕਰਦੇ ਹਨ ਅਤੇ ਫਿਰ ਵੀ ਹੈਰਾਨ ਰਹਿ ਜਾਂਦੇ ਹਨ।
Claude Code documentation drift ਲਈ ਸਭ ਤੋਂ ਵਧੀਆ ਤਰ੍ਹਾਂ ਕੰਮ ਕਰਦਾ ਹੈ ਜਦ ਤੁਸੀਂ docs ਨੂੰ ਕੋਡ ਵਾਂਗTreat ਕਰੋ: ਇੱਕ ਛੋਟਾ, ਰਿਵਿਊਯੋਗ ਪੈਚ ਪ੍ਰਸਤਾਵ ਕਰੋ ਅਤੇ ਵਜਹ ਸਮਝਾਓ। "README ਅਪਡੇਟ ਕਰੋ" ਪੁੱਛਣ ਦੀ ਥਾਂ, ਇਸਨੂੰ ਖਾਸ ਫਾਇਲਾਂ ਦੇ ਖਿਲਾਫ਼ diff ਜਨਰੇਟ ਕਰਨ ਲਈ ਕਹੋ। ਰਿਵਿਊਅਰਜ਼ ਨੂੰ ਸਾਫ਼ before/after ਦਿੱਸਦਾ ਹੈ ਅਤੇ ਉਹ ਅਣਹੋਣੀ ਸੋਧਾਂ ਨੂੰ ਤੇਜ਼ੀ ਨਾਲ ਪਛਾਣ ਸਕਦੇ ਹਨ।
ਇੱਕ ਵਧੀਆ drift ਚੈਕ ਦੋ ਚੀਜ਼ਾਂ ਉਤਪਾਦ ਕਰਦਾ ਹੈ:
ਜਦ ਤੁਸੀਂ ਪ੍ਰੋਮਪਟ ਦਿੰਦੇ ਹੋ, ਰੇਪੋ ਤੋਂ ਪ੍ਰਮਾਣ ਮੰਗੋ: ਫਾਇਲ ਪਾਥ ਅਤੇ ਉਹ ਵੇਰਵੇ ਜਿਵੇਂ ਰੂਟਸ, config ਮੁੱਲ, ਜਾਂ ਇੰਟੀਗਰੇਸ਼ਨ ਟੈਸਟ ਜੋ ਮੌਜੂਦਾ ਬਿਹੇਵਿਅਰ ਦਾ ਪ੍ਰਮਾਣ ਦਿੰਦੇ ਹੋਣ।
ਇੱਥੇ ਇੱਕ ਪ੍ਰੋਮਪਟ ਪੈਟਰਨ ਹੈ ਜੋ ਇਸਨੂੰ ਜ਼ਮੀਨੀ ਰੱਖਦਾ ਹੈ:
Check these docs for drift: README.md, docs/api.md, runbooks/deploy.md.
Compare them to the current repo.
Output:
1) Contradictions list (doc claim -> repo evidence with file path and line range)
2) Unified diffs for the smallest safe edits
Rules: do not rewrite sections that are still accurate.
ਜੇ Claude ਕਹਿੰਦਾ "the API uses /v2", ਤਾਂ ਉਹ ਰਾਊਟਰ, OpenAPI spec, ਜਾਂ ਇੱਕ ਇੰਟੀਗਰੇਸ਼ਨ ਟੈਸਟ ਵੱਲ ਇਸ਼ਾਰਾ ਕਰਕੇ ਉਸ ਦਾ ਸਬੂਤ ਦਿੱਤੇ। ਜੇ ਇਹ ਸਬੂਤ ਨਹੀਂ ਲੱਭ ਸਕਦਾ, ਤਾਂ ਉਸ ਨੂੰ ਇਹ ਕਹਿਣਾ ਚਾਹੀਦਾ ਹੈ।
ਡਰਿਫਟ ਅਕਸਰ ਇੱਕ ਕੋਡ ਤਬਦੀਲੀ ਨਾਲ ਸ਼ੁਰੂ ਹੁੰਦਾ ਹੈ ਜੋ ਖਾਮੋਸ਼ੀ ਨਾਲ ਕਈ ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ ਪ੍ਰਭਾਵਿਤ ਕਰਦੀ ਹੈ। ਪਹਿਲਾਂ Claude ਨੂੰ ਪ੍ਰਭਾਵ ਦਾ ਘੇਰਾ ਦੱਸੋ: ਕੀ ਬਦਲਿਆ, ਕਿੱਥੇ ਬਦਲਿਆ, ਕਿਹੜੇ docs ਟੁੱਟ ਸਕਦੇ ਹਨ, ਅਤੇ ਕਿਹੜੇ ਯੂਜ਼ਰ ਪ੍ਰਭਾਵਿਤ ਹੋਣਗੇ।
ਉਦਾਹਰਨ: ਤੁਸੀਂ ਇੱਕ environment variable ਦਾ ਨਾਂ API_KEY ਤੋਂ SERVICE_TOKEN ਕਰ ਦਿੱਤਾ। ਇੱਕ ਵਧੀਆ ਰਿਪੋਰਟ ਪੁਰਾਣੇ ਨਾਂ ਦੀ ਹਰ ਥਾਂ ਖੋਜੇਗੀ (README setup, API ਉਦਾਹਰਣ, runbook secrets ਸੈਕਸ਼ਨ), ਫਿਰ ਇੱਕ ਟ tight(diff) ਜਨਰੇਟ ਕਰੇਗੀ ਜੋ ਸਿਰਫ਼ ਉਹ ਲਾਈਨਾਂ ਅਪਡੇਟ ਕਰੇ ਜੋ ਹੁਣ ਫੇਲ ਹੋਣਗੀਆਂ।
ਜੇ ਤੁਸੀਂ ਕਿਸੇ ਮਾਡਲ ਨੂੰ "ਸਾਰੇ docs" ਵੱਲ ਬਿਨਾਂ ਨਿਯਮਾਂ ਦੇ ਪਇੰਟ ਕਰੋਗੇ, ਤਾਂ ਅਕਸਰ ਤੁਹਾਨੂੰ ਦੁਬਾਰਾ ਲਿਖਿਆ prose ਮਿਲੇਗਾ ਜੋ ਅਜੇ ਵੀ ਗਲਤ ਤੱਥ ਰੱਖਦਾ ਹੈ। ਇੱਕ ਸਧਾਰਨ workflow ਸੋਧਾਂ ਨੂੰ ਛੋਟਾ, ਦੋਹਰਾਉਣਯੋਗ, ਅਤੇ ਰਿਵਿਊਯੋਗ ਰੱਖਦਾ ਹੈ।
ਇੱਕ doc ਸੈੱਟ ਨਾਲ ਸ਼ੁਰੂ ਕਰੋ: README, API ਰੈਫਰੈਂਸ, ਜਾਂ ਇੱਕ ਅਜਿਹਾ runbook ਜੋ ਲੋਕ ਅਸਲ ਵਿੱਚ ਵਰਤਦੇ ਹਨ। ਇੱਕ ਖੇਤਰ ਨੂੰ ਅਖੀਰ ਤਕ ਠੀਕ ਕਰਨਾ ਤੁਹਾਨੂੰ ਦੱਸੇਗਾ ਕਿ ਕਿਹੜੇ ਸਿਗਨਲ ਭਰੋਸੇਯੋਗ ਹਨ, ਉਸ ਤੋਂ ਬਾਅਦ ਵਧਾਓ।
ਸਾਦਾ ਸ਼ਬਦਾਂ ਵਿੱਚ ਲਿਖੋ ਕਿ ਉਸ doc ਸੈੱਟ ਲਈ ਤੱਥ ਕਿੱਥੋਂ ਆਉਣਗੇ।
ਇਕ ਵਾਰੀ ਤੁਸੀਂ ਉਹ ਸਰੋਤ ਨਾਂਮ ਲਿਖ ਲਏ, ਪ੍ਰੌਮਪਟ ਹੋਰ ਨਿਗਰਾਨ ਹੋ ਜਾਂਦੇ ਹਨ: "README ਨੂੰ ਮੌਜੂਦਾ CLI output ਅਤੇ config defaults ਨਾਲ ਤੁਲਨਾ ਕਰੋ, ਫਿਰ ਇੱਕ patch ਜਨਰੇਟ ਕਰੋ।"
ਪਹਿਲੇ ਚੈਕ ਕਰਨ ਤੋਂ ਪਹਿਲੇ ਆਉਟਪੁੱਟ ਫਾਰਮੈਟ 'ਤੇ ਸਹਿਮਤ ਹੋ ਜਾਓ। ਫਾਰਮੈਟ ਮਿਲਾਉਣ ਨਾਲ ਇਹ ਮੁਸ਼ਕਲ ਹੁੰਦਾ ਹੈ ਕਿ ਕੀ ਬਦਲਿਆ ਅਤੇ ਕਿਉਂ।
ਇੱਕ ਸਧਾਰਨ ਨਿਯਮ-ਸੈੱਟ:
ਇਕ ਪ੍ਰਯੋਗਿਕ ਆਦਤ: ਹਰ doc PR ਵਿੱਚ ਇੱਕ ਛੋਟਾ ਨੋਟ ਜੋੜੋ: "Source of truth checked: routes + tests" ਤਾਂ ਕਿ ਰਿਵਿਊਅਰ ਜਾਣ ਸਕਣ ਕਿ ਕੀ ਤੁਲਨਾ ਕੀਤੀ ਗਈ। ਇਹ doc ਅਪਡੇਟਾਂ ਨੂੰ "ਲੱਗਦਾ ਠੀਕ ਹੈ" ਤੋਂ "ਕਿਸੇ ਨਿਸ਼ਚਿਤ ਚੀਜ਼ ਦੇ ਮੁਕਾਬਲੇ ਵੇਰੀਫਾਈਡ" ਵਿੱਚ ਬਦਲ ਦਿੰਦਾ ਹੈ।
ਹਰ ਕੋਡ ਤਬਦੀਲੀ ਨੂੰ ਇੱਕ ਛੋਟੀ docs ਜਾਂਚ ਸਮਝੋ। ਮਕਸਦ ਇਹ ਹੈ ਕਿ ਵਿਵਾਦਾਂ ਨੂੰ ਜਲਦੀ ਪਕੜਿਆ ਜਾਵੇ ਅਤੇ ਇੱਕ ਛੋਟਾ ਪੈਚ ਤਿਆਰ ਕੀਤਾ ਜਾਵੇ ਜੋ ਰਿਵਿਊਅਰ ਭਰੋਸਾ ਕਰ ਸਕਦੇ ਹਨ।
ਪਹਿਲਾਂ, ਉਹ ਨਿਰਧਾਰਤ ਫਾਇਲਾਂ ਚੁਣੋ ਜਿਨ੍ਹਾਂ ਦੀ ਤੁਸੀਂ ਜਾਂਚ ਕਰਨਾ ਚਾਹੁੰਦੇ ਹੋ ਅਤੇ ਇੱਕ ਸਪਸ਼ਟ drift ਸਵਾਲ। ਉਦਾਹਰਨ: "ਕੀ ਅਸੀ ਕਿਸੇ environment variable, CLI flag, HTTP route, ਜਾਂ error code ਨੂੰ ਬਦਲਿਆ ਹੈ ਜੋ ਦਸਤਾਵੇਜ਼ ਅਜੇ ਵੀ ਉੱਲੇਖ ਕਰ ਰਹੇ ਹਨ?" ਵਿਸ਼ੇਸ਼ ਬਣਨਾ ਮਾਡਲ ਨੂੰ ਪੂਰੇ ਸੈਕਸ਼ਨ ਰੀ-ਰਾਈਟ ਕਰਨ ਤੋਂ ਰੋਕਦਾ ਹੈ।
ਅਗਲੇ ਕਦਮ ਵਿੱਚ, Claude Code ਨੂੰ ਪਹਿਲਾਂ ਕੋਡ ਤੋਂ ਕਠੋਰ ਤੱਥ ਨਿਕਾਲਣ ਲਈ ਕਹੋ। ਇਸਨੂੰ ਸਿਰਫ਼ ਕংਕਰੀਟ ਆਈਟਮ ਲਿਸਟ ਕਰਨ ਲਈ ਕਹੋ: ਯੂਜ਼ਰ ਜੋ ਕਮਾਂਡ ਚਲਾਉਂਦੇ ਹਨ, endpoints ਅਤੇ methods, request ਅਤੇ response ਫੀਲਡ, config keys, ਲੋੜੀਂਦੇ environment variables, ਅਤੇ ਸਕ੍ਰਿਪਟ ਜਾਂ configs ਦੁਆਰਾ ਹਵਾਲੇ ਕੀਤੇ operational steps। ਜੇ ਕੁਝ ਕੋਡ ਵਿੱਚ ਨਹੀਂ ਮਿਲਦਾ, ਤਾਂ ਉਹ "not found" ਕਹੇ ਨਾ ਕਿ ਅਨੁਮਾਨ ਲਗਾਏ।
ਫਿਰ ਇੱਕ ਸਧਾਰਨ ਤੁਲਨਾਤਮਕ ਸਾਰਣੀ ਮੰਗੋ: doc claim, ਜੋ ਕੋਡ ਦਿਖਾਉਂਦਾ ਹੈ, ਅਤੇ ਇੱਕ ਸਥਿਤੀ (match, mismatch, missing, unclear)। ਇਹ ਗੱਲਬਾਤ ਨੂੰ ਜ਼ਮੀਨੀ ਰੱਖਦੀ ਹੈ।
ਉਸ ਤੋਂ ਬਾਅਦ, ਇੱਕ unified diff ਮੰਗੋ ਜੋ ਨਿੱਕੀਆਂ ਸੋਧਾਂ ਕਰੇ। ਦੱਸੋ ਕਿ ਸਿਰਫ਼ ਉਹ ਲਾਈਨਾਂ ਬਦਲੋ ਜੋ mismatch ਨੂੰ ਸਲਾਹਦੇ ਹਨ, doc ਦੀ ਮੌਜੂਦਾ ਸ਼ੈਲੀ ਰੱਖੋ, ਅਤੇ ਉਹ ਵਾਅਦੇ ਨਾ ਜੋੜੋ ਜੋ ਕੋਡ ਦੁਆਰਾ ਸਬੂਤਿਤ ਨਹੀਂ ਹਨ।
ਅੰਤ ਵਿੱਚ, ਇੱਕ ਛੋਟਾ ਰਿਊਵੀਅਰ ਸੰਖੇਪ ਦਿਓ: ਕੀ ਬਦਲਿਆ, ਕਿਉਂ ਬਦਲਿਆ, ਅਤੇ ਕਿਹੜੀਆਂ ਚੀਜ਼ਾਂ ਨੂੰ ਦੁਬਾਰਾ ਚੈੱਕ ਕਰਨਾ ਹੈ (ਜਿਵੇਂ renamed env var ਜਾਂ ਨਵਾਂ ਲੋੜੀਂਦਾ header)।
API docs ਉਦਾਹਰਣ ਦੇ ਤੌਰ 'ਤੇ ਡਰਿਫਟ ਹੁੰਦੇ ਹਨ ਜਦੋਂ ਕੋਡ ਖਾਮੋਸ਼ੀ ਨਾਲ ਬਦਲਦਾ ਹੈ: ਇੱਕ route rename ਹੋ ਜਾਂਦਾ ਹੈ, ਇੱਕ ਫੀਲਡ required ਹੋ ਜਾਂਦੀ ਹੈ, ਜਾਂ error shape ਬਦਲ ਜਾਂਦੀ ਹੈ। ਨਤੀਜਾ ਤੋੜ-ਜੋੜ ਕਲਾਇੰਟ ਇੰਟੀਗਰੇਸ਼ਨ ਅਤੇ ਬੇਕਾਰ ਡਿਬੱਗਿੰਗ ਸਮਾਂ ਹੈ।
Claude Code documentation drift ਲਈ ਕੰਮ ਕਰਦਾ ਹੈ ਤਾਂ ਜੋ ਰੇਪੋ ਤੋਂ ਇਹ ਸਾਬਤ ਕੀਤਾ ਜਾਵੇ ਕਿ API ਕੀ ਕਰਦੀ ਹੈ, ਫਿਰ docs ਵਿੱਚ mismatch ਵਾਲੀਆਂ ਥਾਂਵਾਂ ਨੂੰ ਨੁਕਸਾਨ ਦਿਖਾਓ। ਇਸਨੂੰ routing ਅਤੇ handlers ਤੋਂ ਇਕ ਇਨਵੈਂਟਰੀ ਨਿਕਾਲਣ ਲਈ ਕਹੋ (paths, methods, request ਅਤੇ response ਮਾਡਲ) ਅਤੇ ਉਸਨੂੰ API reference ਨਾਲ ਤੁਲਨਾ ਕਰਵਾਓ।
ਉਸ 'ਤੇ ਧਿਆਨ ਦਿਓ ਜੋ ਲੋਕ ਅਸਲ ਵਿੱਚ ਕਾਪੀ-ਪੇਸਟ ਕਰਦੇ ਹਨ: curl commands, headers, sample payloads, status codes, ਅਤੇ field names। ਇਕ ਹੀ ਪ੍ਰੋਮਪਟ ਵਿੱਚ ਇਹ ਚੈੱਕ ਕਰਵਾਓ:
ਜਦੋਂ ਇਹ mismatch ਲੱਭਦਾ ਹੈ, ਤਾਂ ਕੇਵਲ ਉਹਨਾਂ diffs ਨੂੰ ਸਵੀਕਾਰ ਕਰੋ ਜਿੱਥੇ ਇਹ ਕੋਡ ਤੋਂ ਸਬੂਤ ਦਿਖਾ ਸਕੇ (ਸਹੀ route definition, handler davranış, ਜਾਂ schema)। ਇਹ patches ਛੋਟੇ ਅਤੇ ਰਿਵਿਊਯੋਗ ਰਹਿੰਦੇ ਹਨ।
ਉਦਾਹਰਨ: ਹੁਣ ਕੋਡ POST /widgets 'ਤੇ 201 ਰਿਟਰਨ ਕਰਦਾ ਹੈ ਅਤੇ name ਫੀਲਡ required ਕਰ ਦਿੱਤੀ ਗਈ ਹੈ। docs ਹਾਲੇ ਵੀ 200 ਦੱਸ ਰਹੇ ਹਨ ਅਤੇ name ਨੂੰ ਛੱਡ ਰਹੇ ਹਨ। ਇੱਕ ਵਧੀਆ ਆਉਟਪੁੱਟ ਦੋਵਾਂ contradictions ਨੂੰ ਕਹੇਗਾ ਅਤੇ ਸਿਰਫ਼ ਉਸ ਐਂਡਪਾਇੰਟ ਦੀ status code ਅਤੇ example JSON ਅੱਪਡੇਟ ਕਰੇਗਾ, ਬਾਕੀ ਛੱਡ ਦੇਵੇਗਾ।
Runbooks ਸਭ ਤੋਂ ਮਹਿੰਗੇ ਤਰੀਕੇ ਨਾਲ fail ਕਰਦੇ ਹਨ: ਉਹ ਪੂਰੇ ਦਿਖਦੇ ਹਨ, ਪਰ ਕਦਮ ਹੁਣ ਪ੍ਰਣਾਲੀ ਦੀ ਹਕੀਕਤ ਨਾਲ ਮੇਲ ਨਹੀਂ ਖਾਂਦੇ। ਇੱਕ ਛੋਟੀ ਤਬਦੀਲੀ ਜਿਵੇਂ ਇਹਨਾਂ variables ਦਾ ਨਾਂ ਬਦਲਣਾ ਜਾਂ deploy ਕਮਾਂਡ ਬਦਲਣਾ incident ਨੂੰ ਲੰਬਾ ਕਰ ਸਕਦਾ ਹੈ ਕਿਉਂਕਿ responders ਉਹਨਾਂ ਨਿਰਦੇਸ਼ਾਂ 'ਤੇ ਚੱਲਦੇ ਹਨ ਜੋ ਹੁਣ ਕੰਮ ਨਹੀਂ ਕਰਦੇ।
Runbook ਨੂੰ ਕੋਡ ਵਾਂਗTreat ਕਰੋ: ਮੌਜੂਦਾ ਰੇਪੋ ਦੇ ਖਿਲਾਫ diff ਮੰਗੋ ਅਤੇ contradiction callouts ਲੋੜੀਂਦੇ ਕਰੋ। ਇਸਨੂੰ ਉਹ ਚੀਜ਼ਾਂ ਨਾਲ ਤੁਲਨਾ ਕਰੋ ਜੋ ਸਿਸਟਮ ਅਸਲ ਵਿੱਚ ਵਰਤਦਾ ਹੈ: scripts, config defaults, ਅਤੇ ਤੁਹਾਡੀ ਮੌਜੂਦਾ ਟੂਲਿੰਗ।
ਉਹ failure points 'ਤੇ ਧਿਆਨ ਦਿਓ ਜੋ incidents ਦੌਰਾਨ ਸਭ ਤੋਂ ਜ਼ਿਆਦਾ ਥਰੈਸ਼ ਪੈਦਾ ਕਰਦੇ ਹਨ:
ਕੁਝ quick prechecks ਅਤੇ expected outputs ਵੀ ਜੋੜੋ ਤਾਂ ਕਿ responders ਦੱਸ ਸਕਣ ਕਿ ਉਹ ਸਹੀ ਰਸਤੇ 'ਤੇ ਹਨ। "Verify it works" ਕਾਫ਼ੀ ਨਹੀਂ; ਉਹ ਸਪੱਸ਼ਟ signal ਹੋਣਾ ਚਾਹੀਦਾ ਹੈ (ਇੱਕ status line, version string, ਜਾਂ health check response)।
ਜੇ ਤੁਸੀਂ Koder.ai ਜਿਹੇ ਪਲੇਟਫਾਰਮਾਂ 'ਤੇ ਐਪ ਬਣਾਉਂਦੇ ਅਤੇ deploy ਕਰਦੇ ਹੋ, ਤਾਂ ਇਹ ਹੋਰ ਵੀ ਜ਼ਰੂਰੀ ਹੋ ਜਾਂਦਾ ਹੈ ਕਿਉਂਕਿ snapshots ਅਤੇ rollback ਉਸ ਵੇਲੇ ਹੀ ਉਪਯੋਗੀ ਹੁੰਦੇ ਹਨ ਜਦੋਂ runbook ਸਹੀ ਕਾਰਵਾਈ ਦਾ ਨਾਂ ਦੱਸਦਾ ਹੈ ਅਤੇ ਮੌਜੂਦਾ recovery path ਨੂੰ ਦਰਸਾਉਂਦਾ ਹੈ।
ਡਰਿਫਟ ਬਣਾਉਣ ਦਾ ਸਭ ਤੋਂ ਤੇਜ਼ ਤਰੀਕਾ ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ "ਚੰਗੀ ਲਿਖਤ" ਵਾਂਗ ਸਮਝਣਾ ਹੈ ਨਾ ਕਿ ਉਹਨਾਂ ਦਾਅਵਿਆਂ ਦੇ ਸੈੱਟ ਜੋ ਕੋਡ ਨਾਲ ਮਿਲਦੇ ਹੋਣ।
ਇੱਕ ਆਮ ਗਲਤੀ ਪਹਿਲਾਂ rewrite ਮੰਗਣਾ ਹੈ। ਜਦੋਂ ਤੁਸੀਂ contradiction ਚੈੱਕ ਛੱਡ ਦਿੰਦੇ ਹੋ, ਤਾਂ ਤੁਹਾਨੂੰ चिकਨ-ਚੌਪ prose ਮਿਲ ਸਕਦੀ ਹੈ ਜੋ ਹਾਲੇ ਵੀ ਗਲਤ ਵਿਹੇਵਿਅਰ ਦਰਸਾਉਂਦੀ ਹੈ। ਹਮੇਸ਼ਾ ਪਹਿਲਾਂ ਪੁੱਛੋ ਕਿ ਦਸਤਾਵੇਜ਼ ਕੀ ਦਾਅਵਾ ਕਰਦਾ ਹੈ, ਕੋਡ ਕੀ ਕਰਦਾ ਹੈ, ਅਤੇ ਕਿੱਥੇ ਉਹ ਅਣ-ਮਿਲਦੇ ਹਨ।
ਹੋਰ ਗਲਤੀ ਮਾਡਲ ਨੂੰ ਅਨੁਮਾਨ ਲਗਾਉਣ ਦਿੰਨਾ ਹੈ। ਜੇ ਬਿਹੇਵਿਅਰ ਕੋਡ, tests, ਜਾਂ configs ਵਿੱਚ ਦਿਖਾਈ ਨਹੀਂ ਦਿੰਦਾ, ਤਾਂ ਉਸਨੂੰ uncertain ਮੰਨਾਂ। "Probably" README ਵਿੱਚ ਵਾਅਦੇ ਬਣਾਉਂਦਾ ਹੈ ਅਤੇ runbooks ਕਹਾਣੀਵੀਂ ਹੋ ਸਕਦੇ ਹਨ।
ਇਹ ਸਮੱਸਿਆਵਾਂ ਰੋਜ਼ਾਨਾ ਅਪਡੇਟਾਂ ਵਿੱਚ ਕਾਫ਼ੀ ਆਉਂਦੀਆਂ ਹਨ:
ਇੱਕ handler expired tokens ਲਈ 401 ਦੀ ਥਾਂ 403 ਰਿਟਰਨ ਕਰਦਾ ਹੈ, ਅਤੇ header ਨਾਮ X-Token ਤੋਂ Authorization ਹੋ ਜਾਂਦਾ ਹੈ। ਜੇ ਤੁਸੀਂ ਸਿਰਫ਼ auth सेकਸ਼ਨ ਰੀ-ਰਾਈਟ ਕਰੋਗੇ, ਤਾਂ ਤੁਸੀਂ ਮਿਸ ਕਰ ਸਕਦੇ ਹੋ ਕਿ API doc example ਹਾਲੇ ਵੀ ਪੁਰਾਣਾ header ਦਿਖਾ ਰਿਹਾ ਹੈ, ਅਤੇ runbook ਹਾਲੇ ਵੀ on-call ਨੂੰ 401 spikes ਦੇਖਣ ਨੂੰ ਕਹਿ ਰਹੀ ਹੈ।
ਜਦੋਂ ਤੁਸੀਂ diffs ਬਣਾਉਂਦੇ ਹੋ, ਇੱਕ ਛੋਟਾ ਫੈਸਲਾ-ਲਾਈਨ ਜੋੜੋ ਜਿਵੇਂ: "Auth failures ਹੁਣ 403 ਰਿਟਰਨ ਕਰਦੇ ਹਨ ਤਾਂ ਜੋ invalid ਅਤੇ missing credentials ਨੂੰ ਫਰਕ ਕੀਤਾ ਜਾਵੇ." ਇਹ ਅਗਲੇ ਵਿਅਕਤੀ ਨੂੰ ਰੋਕਦਾ ਹੈ ਕਿ ਉਹ docs ਨੂੰ ਪੁਰਾਣੇ ਵਿਹੇਵਿਅਰ ਵੱਲ ਮੁੜ-ਵਾਪਸ ਕਰ ਦੇਵੇ।
ਹਰ doc ਅਪਡੇਟ ਨੂੰ ਇੱਕ ਛੋਟੀ ਆਡਿਟ ਵਾਂਗ ਸਮਝੋ। ਮਕਸਦ ਅਗਲੀ ਵਾਰੀ ਜਦੋਂ ਕੋਈ ਨਿਰਦੇਸ਼ ਫੋਲੋ ਕਰੇ ਤਾਂ ਘੱਟ ਹੈਰਾਨੀਆਂ ਹੋਣ।
Merge ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ README, API docs, ਅਤੇ runbook ਵਿੱਚ ਹਰ ਇਕ concrete claim ਜਿਹੜਾ ਕਮਾਂਡ, endpoint, config key, env var, port, ਜਾਂ example payload ਦੱਸਦਾ ਹੈ, ਨੂੰ ਹਾਈਲਾਈਟ ਕਰੋ।
ਜੇ ਤੁਸੀਂ ਇੱਕੋ ਦਸਤਾਵੇਜ਼ ਵਿੱਚ ਦੋ ਜਾਂ ਵੱਧ unknown claims ਲੱਭਦੇ ਹੋ, ਤਾਂ merge ਰੋਕੋ। ਜਾਂ ਤਾਂ ਸਬੂਤ (file paths ਅਤੇ function names) ਜੋੜੋ, ਜਾਂ doc ਨੂੰ ਉਸੇ ਹਿੱਸੇ ਤੱਕ ਘਟਾ ਦਿਓ ਜੋ ਨਿਸ਼ਚਿਤ ਹੈ।
ਇੱਕ ਛੋਟੀ ਟੀਮ auth ਅਪਡੇਟ ਕਰਦੀ ਹੈ: API key ਦੀ ਥਾਂ clients ਹੁਣ Authorization: Bearer <token> ਭੇਜਦੇ ਹਨ। ਕੋਡ ship ਹੁੰਦਾ ਹੈ, tests ਪਾਸ ਹੁੰਦੇ ਹਨ, ਅਤੇ ਟੀਮ ਅੱਗੇ ਵੱਧ ਜਾਂਦੀ ਹੈ।
ਦੋ ਦਿਨ ਬਾਅਦ, ਨਵਾਂ ਡਿਵੈਲਪਰ README ਫੋਲੋ ਕਰਦਾ ਹੈ। README ਹਾਲੇ ਵੀ ਕਹਿੰਦਾ ਹੈ "set X-API-Key in your environment" ਅਤੇ curl ਉਦਾਹਰਣ ਪੁਰਾਣਾ header ਦਿਖਾਂਦੀ ਹੈ। ਉਹ ਲੋਕਲ ਰਨ ਨਹੀਂ ਚਲਾ ਪਾਂਦਾ ਅਤੇ ਸੋਚਦਾ ਹੈ ਕਿ ਸੇਵਾ ਡਾਊਨ ਹੈ।
ਇਸ ਦਰਮਿਆਨ, API docs ਵੀ stale ਹਨ। ਉਹ ਪੁਰਾਣਾ header ਵਰਣਨ ਕਰਦੇ ਹਨ ਅਤੇ ਹਾਲੇ ਵੀ ਇੱਕ response field user_id ਦਿਖਾਉਂਦੇ ਹਨ, ਜਦਕਿ API ਹੁਣ userId ਰਿਟਰਨ ਕਰਦੀ ਹੈ। ਲਿਖਤ ਵਿਚ ਕੋਈ ਗਲਤੀ ਨਹੀਂ, ਪਰ ਇਹ ਕੋਡ ਨਾਲ ਟਕਰਾਉਂਦੀ ਹੈ, ਇਸ ਲਈ ਪੜ੍ਹਨ ਵਾਲੇ ਗਲਤ ਚੀਜ਼ਾਂ ਕਾਪੀ ਕਰ ਲੈਂਦੇ ਹਨ।
ਫਿਰ ਇੱਕ incident ਹੁੰਦਾ ਹੈ। On-call runbook ਦੀ ਕਦਮ "rotate the API key and restart workers" ਫੋਲੋ ਕਰਦਾ ਹੈ। ਇਹ ਮਦਦ ਨਹੀਂ ਕਰਦਾ ਕਿਉਂਕਿ ਅਸਲ ਸਮੱਸਿਆ token verification ਨਾਲ ਸੰਬੰਧਿਤ ਹੈ। runbook 20 ਮਿੰਟ ਲਈ ਉਨ੍ਹਾਂ ਨੂੰ ਗਲਤ ਰਸਤੇ ਭੇਜਦਾ ਹੈ।
ਇਥੇ Claude Code documentation drift ਦੀ ਵਰਤੋਂ ਮਦਦਗਾਰ ਹੁੰਦੀ ਹੈ ਜਦੋਂ ਇਹ diffs ਅਤੇ contradiction callouts ਤਿਆਰ ਕਰਦਾ ਹੈ, ਨਾ ਕਿ ਪੂਰੀ ਰੀ-ਰਾਈਟ। ਤੁਸੀਂ ਇਸਨੂੰ ਕਹਿ ਸਕਦੇ ਹੋ ਕਿ auth middleware ਅਤੇ route handlers ਨੂੰ README snippets, API examples, ਅਤੇ runbook steps ਨਾਲ ਤੁਲਨਾ ਕਰ ਕੇ ਘੱਟੋ-ਘੱਟ ਪੈਚ ਪ੍ਰਸਤਾਵ ਕਰੋ:
- Header: X-API-Key: <key>
+ Header: Authorization: Bearer <token>
- { "user_id": "..." }
+ { "userId": "..." }
ਅਹਮ ਗੱਲ ਇਹ ਹੈ ਕਿ ਇਹ mismatches ਨੂੰ ਨਿਸ਼ਾਨਾ ਲਗਾਉਂਦਾ ਹੈ, ਸਹੀ ਥਾਵਾਂ ਵੱਲ ਇਸ਼ਾਰਾ ਕਰਦਾ ਹੈ, ਅਤੇ ਸਿਰਫ਼ ਉਹੀ ਚੀਜ਼ਾਂ ਬਦਲਦਾ ਹੈ ਜੋ ਰੇਪੋ ਸਾਬਤ ਕਰਦਾ ਹੈ।
ਦਸਤਾਵੇਜ਼ ਉਸ ਸਮੇਂ ਸਹੀ ਰਹਿੰਦੇ ਹਨ ਜਦੋਂ ਉਨ੍ਹਾਂ ਦੀ ਜਾਂਚ ਬੋਰੀنگ ਅਤੇ ਦੋਹਰਾਉਣਯੋਗ ਹੋ। ਆਪਣੀ cadence ਉਹ ਅਨੁਸਾਰ ਚੁਣੋ ਕਿ ਤੁਹਾਡੇ ਬਦਲਾਅ ਕਿੰਨੇ ਖਤਰਨਾਕ ਹਨ। ਤੇਜ਼ੀ ਨਾਲ ਬਦਲਦੇ ਕੋਡ ਲਈ, ਹਰ PR 'ਤੇ ਇਹ ਕਰੋ। ਸਥਿਰ ਸਰਵਿਸਜ਼ ਲਈ, ਇੱਕ ਹਫ਼ਤੇਵਾਰ sweep ਅਤੇ pre-release check ਕਾਫੀ ਹੋ ਸਕਦਾ ਹੈ।
Docs drift ਨੂੰ ਇੱਕ test failure ਵਾਂਗ ਸਮਝੋ, ਲਿਖਣ ਦਾ ਕੰਮ ਨਹੀਂ। Claude Code documentation drift ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਇੱਕ ਛੋਟਾ diff ਅਤੇ contradictions ਦੀ ਛੋਟੀ ਲਿਸਟ ਜਨਰੇਟ ਕਰੋ, ਫਿਰ ਉਹਨਾਂ ਤੋਂ ਛੋਟਾ-ਸਭ ਤੋਂ ਕੰਮ ਕਰੋ ਜੋ docs ਨੂੰ ਦੁਬਾਰਾ ਸੱਚਾ ਬਣਾ ਦੇਵੇ।
ਲੈਟ-ਵਜ਼ਨ workflow ਜੋ ਹਲਕਾ ਰਹੇ:
ਉਹ diff summaries ਅਗਲੇ ਸਮੇਂ ਲੱਭਣ ਯੋਗ ਰੱਖੋ। ਇੱਕ ਛੋਟੀ ਨੋਟ ਜਿਵੇਂ "Docs updated to match new /v2 endpoint, removed deprecated header, updated example response" ਮਦਦ ਕਰਦੀ ਹੈ ਜਦੋਂ ਕਿਸੇ ਨੂੰ ਮਹੀਨਿਆਂ ਬਾਅਦ ਪੁੱਛਣਾ ਹੋਵੇ ਕਿ doc ਕਿਉਂ ਬਦਲਿਆ।
Docs ਤੇ ਵੀ "snapshots and rollback" ਸੋਚ ਲਗਾਓ। ਜੇ ਕੋਈ ਨਿਰਦੇਸ਼ ਅਣਿਸ਼ਚਿਤ ਹੈ, ਤਾਂ ਪਹਿਲਾਂ ਇੱਕ ਥਾਂ 'ਤੇ ਬਦਲੋ, ਤੇਜ਼ੀ ਨਾਲ ਵੈਰੀਫਾਈ ਕਰੋ, ਫਿਰ ਪੁਸ਼ਟੀ ਸੰਸਕਰਣ ਹੋਰ ਥਾਵਾਂ 'ਤੇ ਨકલ ਕਰੋ।
ਜੇ ਤੁਸੀਂ ਤੇਜ਼ੀ ਨਾਲ ਬਣਾਉਂਦੇ ਹੋ, ਤਾਂ Koder.ai (koder.ai) ਵਿੱਚ ਐਪ ਅਤੇ ਉਸ ਦੀ ਪਹਿਲੀ docs ਇੱਕਠੇ ਜਨਰੇਟ ਕਰਨ ਨਾਲ ਮਦਦ ਮਿਲ ਸਕਦੀ ਹੈ, ਫਿਰ ਸੋਲੇਅਲੇ ਸੋਰਸ ਕੋਡ export ਕਰੋ ਅਤੇ ਆਪਣੇ ਆਮ workflow ਵਿੱਚ ਸੋਧਾਂ ਰਿਵਿਊਯੋਗ ਰੱਖੋ। ਮਕਸਦ ਸ਼ਾਨਦਾਰ ਪ੍ਰੋਜ਼ ਨਹੀਂ — ਉਹ ਹੈ ਜੋ ਲੋਕ ਕਰਦੇ ਹਨ (ਕਮਾਂਡ, endpoints, steps) ਨੂੰ ਕੋਡ ਨਾਲ ਮਿਲਾਉਣਾ।
Documentation drift ਉਹ ਹੈ ਜਦੋਂ ਤੁਹਾਡੇ ਦਸਤਾਵੇਜ਼ ਹੌਲੇ-ਹੌਲੇ ਉਸ ਗੱਲ ਨਾਲ ਮਿਲਣਾ ਬੰਦ ਕਰ ਦਿੰਦੇ ਜੋ ਕੋਡ ਕਰਦਾ ਹੈ। ਇਹ ਆਮ ਤੌਰ 'ਤੇ ਨਿੱਕੀਆਂ-ਨਿੱਕੀਆਂ ਤਬਦੀਲੀਆਂ ਤੋਂ ਸ਼ੁਰੂ ਹੁੰਦਾ ਹੈ (ਜਿਵੇਂ ਕਿਸੇ env var ਦਾ ਨਾਂ ਬਦਲਣਾ, ਕੋਈ ਨਵਾਂ ਜ਼ਰੂਰੀ ਫੀਲਡ, ਜਾਂ ਸਟੇਟਸ ਕੋਡ ਬਦਲਣਾ) ਜੋ README, API ਉਦਾਹਰਣਾਂ ਜਾਂ runbooks 'ਚ ਨਹੀਂ ਦਿਖਾਇਆ ਜਾਂਦਾ।
ਕਿਉਂਕਿ ਕੋਡ ਦਬਾਅ ਹੇਠਾਂ ਤੇਜ਼ੀ ਨਾਲ ਬਦਲਦਾ ਹੈ ਪਰ ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ ਉਸੇ ਤਰ੍ਹਾਂ ਨਿਯਮ ਨਹੀਂ ਮਿਲਦੇ।
ਆਮ ਕਾਰਨ:
ਉਹ ਦਸਤਾਵੇਜ਼ ਜਿਨ੍ਹਾਂ ਨੂੰ ਲੋਕ ਅਸਲ ਵਿੱਚ ਚਲਾਉਂਦੇ ਹਨ — ਨੁਕਸਾਨ ਘੱਟ ਕਰਨ ਲਈ ਪਹਿਲਾਂ ਉਨ੍ਹਾਂ ਨੂੰ ਚੈੱਕ ਕਰੋ। ਪ੍ਰਾਇਰਟੀ ਦਾ ਕ੍ਰਮ:
ਇਹ ਪਹਿਲੇ ਫਿਕਸ ਕਰਨ ਨਾਲ ਸਭ ਤੋਂ ਮਹਿੰਗੇ ਨਤੀਜੇ ਘਟ ਜਾਂਦੇ ਹਨ।
ਕਿੱਲੀ ਗੱਲ ਇਹ ਹੈ ਕਿ ਸੁਆਹਰ ਬਹਿਤਰੀਨ ਲਿਖਾਈ ਵੀ ਗਲਤ ਹੋ ਸਕਦੀ ਹੈ। ڈرِفٹ ਮੁੱਖ ਤੌਰ 'ਤੇ ਗਲਤ 'ਦਾਅਵੇ' ਬਾਰੇ ਹੁੰਦਾ ਹੈ।
ਇਹ ਬੇਹਤਰ ਹੈ ਕਿ ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ ਟੈਸਟਯੋਗ ਬਿਆਨ ਮੰਨਿਆ ਜਾਵੇ: “ਇਹ ਕਮਾਂਡ ਚਲਾਓ”, “ਇਸ ਐਂਡਪਾਇੰਟ ਨੂੰ ਕਾਲ ਕਰੋ”, “ਇਸ ਵੇਰੀਏਬਲ ਨੂੰ ਸੈਟ ਕਰੋ” — ਫਿਰ ਉਹਨਾਂ ਦਾਅਵਿਆਂ ਨੂੰ ਮੌਜੂਦਾ ਰેપੋ, ਕੰਫਿਗ ਅਤੇ ਰਿਅਲ ਆਉਟਪੁੱਟ ਨਾਲ ਵੇਰੀਫਾਈ ਕਰੋ।
ਦੋ ਚੀਜ਼ਾਂ ਮੰਗੋ:
ਅਤੇ ਨਿਯਮ: ਜੇ ਰੇਪੋ ਵਿੱਚ ਸਬੂਤ ਨਹੀਂ ਮਿਲਦਾ, ਤਾਂ ਉਹ ‘not found’ ਕਹੇ ਬਿਨਾਂ ਅਨੁਮਾਨ ਨਾ ਲਗਾਏ।
ਕਿਉਂਕਿ ਰివ്യൂਅਰਜ਼ ਤੇਜ਼ੀ ਨਾਲ diffs ਦੀ ਪੁਸ਼ਟੀ ਕਰ ਸਕਦੇ ਹਨ। ਇੱਕ diff ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਕੁਝ ਕਿੱਥੇ ਬਦਲਿਆ, ਅਤੇ ਇਹ “ਮਦਦਗਾਰ” ਰੀ-ਰਾਇਟਸ ਨੂੰ ਰੋਕਦਾ ਹੈ ਜੋ ਨਵੇਂ ਦਾਅਵੇ ਜੋੜ ਸਕਦੇ ਹਨ।
ਅਚ্ছে ਡਿਫ ਦੀ ਡਿਫਾਲਟ ਨੀਤੀ: ਜੇ ਹੋ ਸਕੇ ਤਾਂ ਇੱਕ ਫਾਇਲ ਪ੍ਰਤੀ ਡਿਫ ਅਤੇ ਹਰ ਬਦਲਾਅ ਲਈ ਇੱਕ-ਵਾਕ ਦਾ ਕਾਰਨ ਜੋ ਰੇਪੋ ਸਬੂਤ ਨਾਲ ਜੁੜਿਆ ਹੋਵੇ।
ਉਸਨੂੰ ਸਬੂਤ ਦੇਣ ਲਈ ਕਹੋ।
ਵੈਕਤਿਗਤ ਨੀਤੀਆਂ:
ਲੋਕ ਅਕਸਰ ਜੋ ਕਾਪੀ-ਪੇਸਟ ਕਰਦੇ ਹਨ ਉਨ੍ਹਾਂ ਨੂੰ ਜਾਂਚੋ:
ਜੇ ਐਂਡਪਾਇੰਟ ਸੂਚੀ ਸਹੀ ਹੈ ਪਰ ਉਦਾਹਰਣ ਗਲਤ ਹਨ, ਤਾਂ ਯੂਜ਼ਰ ਫੇਲ ਹੋ ਜਾਂਦੇ ਹਨ — ਇਸ ਲਈ ਉਦਾਹਰਣਾਂ ਨੂੰ ਉੱਚ ਤਰਜੀਹ ਦਿਓ।
Runbooks ਉਹਨਾਂ ਤਰੀਕਿਆਂ ਵੱਲੇ ਪਸਾਰ ਹੁੰਦੇ ਹਨ ਜਿੱਥੇ ਆਪਰੇਸ਼ਨਲ ਹਕੀਕਤ ਬਦਲ ਜਾਂਦੀ ਹੈ।
ਉੱਚ-ਪ੍ਰਭਾਵ ਵਾਲੀਆਂ ਜਾਂਚਾਂ:
ਜੇ responders ਪ੍ਰਗਤੀ ਵੈਰੀਫਾਈ ਨਹੀਂ ਕਰ ਸਕਦੇ, ਤਾਂ ਉਹ incidents ਦੌਰਾਨ ਸਮਾਂ ਖਰਚ ਕਰਦੇ ਰਹਿੰਦੇ ਹਨ।
ਹਰ ਦਸਤਾਵੇਜ਼ ਕਿਸਮ ਲਈ ਇੱਕ ਸਧਾਰਨ “source of truth” ਨੀਤੀ:
ਫਿਰ ਇਹ workflow ਵਿੱਚ ਜੋੜੋ: ਪ੍ਰਭਾਵਤ ਦਸਤਾਵੇਜ਼ਾਂ 'ਤੇ PR ਵਿੱਚ drift check ਚਲਾਓ, ਅਤੇ ਸੋਧਾਂ ਛੋਟੀਆਂ ਅਤੇ ਰਿਵਿਊਯੋਗ ਰੱਖੋ।