ਤਕਨੀਕੀ ਦਸਤਾਵੇਜ਼ਬੰਦੀ (Technical documentation) ਕੋਈ ਅਜਿਹਾ ਸਾਈਡ ਟਾਸਕ ਨਹੀਂ ਹੈ ਜਿਸ ਨੂੰ ਤੁਸੀਂ ਕੋਡ ਕੰਪਾਈਲ ਹੋਣ ਤੋਂ ਬਾਅਦ ਖਤਮ ਕਰਦੇ ਹੋ। ਇਹ ਹਰ ਸਾਫਟਵੇਅਰ ਪ੍ਰੋਜੈਕਟ ਦੇ ਕੇਂਦਰ ਵਿੱਚ ਹੁੰਦੀ ਹੈ, ਜੋ ਇਹ ਤੈਅ ਕਰਦੀ ਹੈ ਕਿ ਕੀ ਇੱਕ ਨਵਾਂ ਡਿਵੈਲਪਰ ਆਪਣੇ ਪਹਿਲੇ ਦਿਨ ਹੀ ਕਿਸੇ ਬੱਗ (bug) ਨੂੰ ਠੀਕ ਕਰ ਸਕਦਾ ਹੈ ਜਾਂ ਕੀ ਕੋਈ ਯੂਜ਼ਰ ਪੰਜ ਮਿੰਟ ਦੀ ਉਲਝਣ ਤੋਂ ਬਾਅਦ ਤੁਹਾਡੇ ਪ੍ਰੋਡਕਟ ਨੂੰ ਛੱਡ ਦਿੰਦਾ ਹੈ। ਚੰਗੇ ਦਸਤਾਵੇਜ਼ ਯੂਜ਼ਰਸ ਨੂੰ ਅਸਲ ਕੰਮ ਪੂਰੇ ਕਰਨ ਵਿੱਚ ਮਦਦ ਕਰਦੇ ਹਨ। ਉਹ ਭਵਿੱਖ ਦੇ ਮੇਨਟੇਨਰਸ (maintainers) ਨੂੰ ਇਹ ਸਮਝਣ ਵਿੱਚ ਮਦਦ ਕਰਦੇ ਹਨ ਕਿ ਕੋਈ ਮੋਡਿਊਲ ਕਿਉਂ ਮੌਜੂਦ ਹੈ ਅਤੇ ਸਭ ਕੁਝ ਤੋੜੇ ਬਿਨਾਂ ਇਸ ਨੂੰ ਕਿਵੇਂ ਬਦਲਿਆ ਜਾ ਸਕਦਾ ਹੈ। ਫਿਰ ਵੀ ਬਹੁਤ ਸਾਰੀਆਂ ਟੀਮਾਂ ਦਸਤਾਵੇਜ਼ਬੰਦੀ ਨੂੰ ਇੱਕ ਅੰਤਿਮ ਵਿਚਾਰ (afterthought) ਵਜੋਂ ਲੈਂਦੀਆਂ ਹਨ, ਜਿਵੇਂ ਕਿ ਕਾਹਲੀ ਵਿੱਚ ਬਣਾਇਆ ਗਿਆ README, ਜਾਂ ਕੋਈ ਵਿਕੀ (wiki) ਪੇਜ ਜੋ ਖਰਾਬ ਹੋਣ ਲਈ ਛੱਡ ਦਿੱਤਾ ਗਿਆ ਹੋਵੇ। ਅਸਲ ਵਿੱਚ ਲਾਭਦਾਇਕ ਦਸਤਾਵੇਜ਼ ਲਿਖਣਾ ਇੱਕ ਅਜਿਹਾ ਹੁਨਰ ਹੈ ਜਿਸ ਨੂੰ ਤੁਸੀਂ ਜਾਣਬੁੱਝ ਕੇ ਸੁਧਾਰ ਸਕਦੇ ਹੋ।
ਲਿਖਣ ਤੋਂ ਪਹਿਲਾਂ ਆਪਣੇ ਪਾਠਕਾਂ ਨੂੰ ਜਾਣੋ
ਇੱਕ ਵੀ ਹੈਡਿੰਗ ਟਾਈਪ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ, ਇਹ ਫੈਸਲਾ ਕਰੋ ਕਿ ਕੌਣ ਪੜ੍ਹ ਰਿਹਾ ਹੈ। ਇੱਕ ਡਾਟਾਬੇਸ ਐਡਮਿਨਿਸਟ੍ਰੇਟਰ (database administrator) ਜੋ ਕਨੈਕਸ਼ਨ ਪੂਲ ਸੈਟਿੰਗਾਂ ਦੀ ਭਾਲ ਕਰ ਰਿਹਾ ਹੈ, ਉਸਦਾ ਇੱਕ ਫਰੰਟ-ਐਂਡ ਡਿਵੈਲਪਰ ਨਾਲ ਕੋਈ ਸਾਂਝ ਨਹੀਂ ਹੈ ਜੋ React component props ਲੱਭ ਰਿਹਾ ਹੈ। ਅੰਤਿਮ-ਯੂਜ਼ਰਸ (End-users) ਨੂੰ ਨੰਬਰ ਵਾਲੇ ਕਦਮਾਂ ਅਤੇ ਸਕ੍ਰੀਨਸ਼ੌਟਸ ਦੀ ਲੋੜ ਹੁੰਦੀ ਹੈ, ਆਰਕੀਟੈਕਚਰ ਡਾਇਗ੍ਰਾਮ ਦੀ ਨਹੀਂ। ਉਹ ਇਹ ਜਾਣਨਾ ਚਾਹੁੰਦੇ ਹਨ ਕਿ PDF ਨੂੰ ਐਕਸਪੋਰਟ ਕਿਵੇਂ ਕਰਨਾ ਹੈ, ਨਾ ਕਿ ਰੈਂਡਰਿੰਗ ਪਾਈਪਲਾਈਨ ਕਿਵੇਂ ਕੰਮ ਕਰਦੀ ਹੈ। ਤੁਹਾਡੀ ਲਾਇਬ੍ਰੇਰੀ (library) ਨੂੰ ਇੰਟੀਗ੍ਰੇਟ ਕਰਨ ਵਾਲੇ ਡਿਵੈਲਪਰਸ ਨੂੰ ਸਹੀ ਫੰਕਸ਼ਨ ਸਿਗਨੇਚਰ (function signatures), ਐਰਰ ਕੋਡ (error codes), ਅਤੇ ਕਾਪੀ-ਪੇਸਟ ਕਰਨ ਯੋਗ ਸਨਿਪੇਟਸ (snippets) ਦੀ ਲੋੜ ਹੁੰਦੀ ਹੈ। ਸਿਸਟਮ ਐਡਮਿਨਿਸਟ੍ਰੇਟਰਸ ਨੂੰ ਇੰਸਟਾਲੇਸ਼ਨ ਦੀਆਂ ਪੂਰਵ-ਸ਼ਰਤਾਂ, ਐਨਵਾਇਰਨਮੈਂਟ ਵੇਰੀਏਬਲਸ (environment variables), ਅਤੇ ਟਰਬਲਸ਼ੂਟਿੰਗ ਫਲੋਅ ਦੀ ਲੋੜ ਹੁੰਦੀ ਹੈ ਜੋ ਸਭ ਤੋਂ ਆਮ ਫੇਲ੍ਹ ਹੋਣ ਵਾਲੇ ਤਰੀਕਿਆਂ ਤੋਂ ਸ਼ੁਰੂ ਹੁੰਦੇ ਹਨ।
ਜੇਕਰ ਤੁਸੀਂ ਇੱਕੋ ਲੰਬੇ ਪੈਰੇ ਨਾਲ ਤਿੰਨਾਂ ਸਮੂਹਾਂ ਦੀ ਸੇਵਾ ਕਰਨ ਦੀ ਕੋਸ਼ਿਸ਼ ਕਰਦੇ ਹੋ, ਤਾਂ ਹਰ ਕੋਈ ਹਾਰ ਜਾਂਦਾ ਹੈ। ਵੱਖਰੇ ਰਸਤੇ ਬਣਾਓ। ਇੱਕ ਸਿੰਗਲ ਪੇਜ ਨੂੰ ਵੀ "ਓਪਰੇਟਰਾਂ ਲਈ" ਅਤੇ "ਕਲਾਇੰਟ ਡਿਵੈਲਪਰਾਂ ਲਈ" ਵਰਗੇ ਸਪਸ਼ਟ ਹੈਡਿੰਗਾਂ ਨਾਲ ਸਾਫ਼ ਤੌਰ 'ਤੇ ਵੰਡਿਆ ਜਾ ਸਕਦਾ ਹੈ। ਮਕਸਦ ਇਹ ਹੈ ਕਿ "ਕੀ ਇਹ ਪੈਰਾ ਮੇਰੇ ਲਈ ਹੈ?" ਵਰਗੇ ਸਵਾਲਾਂ ਦੀ ਮਾਨਸਿਕ ਉਲਝਣ ਨੂੰ ਖਤਮ ਕਰਨਾ।
ਫਾਲਤੂ ਦੀਆਂ ਗੱਲਾਂ ਘਟਾਓ
ਸਪਸ਼ਟਤਾ ਚਲਾਕੀ ਨਾਲੋਂ ਬਿਹਤਰ ਹੈ। ਛੋਟੇ ਵਾਕਾਂ ਦੀ ਵਰਤੋਂ ਕਰੋ। ਐਕਟਿਵ ਵੌਇਸ (active voice) ਦੀ ਵਰਤੋਂ ਕਰੋ। "Initialize the database" (ਡਾਟਾਬੇਸ ਨੂੰ ਇਨੀਸ਼ੀਅਲਾਈਜ਼ ਕਰੋ) "The database should be initialized by the user" (ਡਾਟਾਬੇਸ ਯੂਜ਼ਰ ਦੁਆਰਾ ਇਨੀਸ਼ੀਅਲਾਈਜ਼ ਕੀਤਾ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ) ਨਾਲੋਂ ਸਪਸ਼ਟ ਹੈ। ਜਦੋਂ ਤੁਹਾਨੂੰ "idempotency" ਜਾਂ "serialization" ਵਰਗੇ ਤਕਨੀਕੀ ਸ਼ਬਦ ਦੀ ਵਰਤੋਂ ਕਰਨੀ ਪਵੇ, ਤਾਂ ਇਸਦੀ ਪਰਿਭਾਸ਼ਾ ਲਾਈਨ ਦੇ ਅੰਦਰ ਹੀ ਦਿਓ ਜਾਂ ਗਲੋਸਰੀ (glossary) ਨਾਲ ਲਿੰਕ ਕਰੋ। ਪਹਿਲਾਂ ਤੋਂ ਮੌਜੂਦ ਗਿਆਨ ਦਾ ਅੰਦਾਜ਼ਾ ਨਾ ਲਗਾਓ।
ਇੱਕ ਵਿਵਹਾਰਕ ਟੈਸਟ: ਆਪਣੇ ਪੈਰੇ ਨੂੰ ਉੱਚੀ ਆਵਾਜ਼ ਵਿੱਚ ਪੜ੍ਹਨ ਦੀ ਕੋਸ਼ਿਸ਼ ਕਰੋ। ਜੇਕਰ ਤੁਹਾਡਾ ਸਾਹ ਫੁੱਲ ਜਾਂਦਾ ਹੈ, ਤਾਂ ਵਾਕ ਬਹੁਤ ਲੰਬਾ ਹੈ। ਇੱਕ ਹੋਰ ਟੈਸਟ: ਸ਼ਾਨਦਾਰ ਕਿਰਿਆਵਾਂ (verbs) ਨੂੰ ਸਧਾਰਨ ਕਿਰਿਆਵਾਂ ਨਾਲ ਬਦਲੋ। ਜੇਕਰ "utilize the API" ਵਰਗੇ ਵਾਕ ਨੂੰ ਅਰਥ ਖੋਏ ਬਿਨਾਂ "use the API" ਵਿੱਚ ਬਦਲਿਆ ਜਾ ਸਕਦਾ ਹੈ, ਤਾਂ ਉਹ ਬਦਲਾਅ ਕਰੋ। ਸਾਦੀ ਭਾਸ਼ਾ ਦਾ ਮਤਲਬ ਮੂਰਖਤਾ ਵਾਲੀ ਭਾਸ਼ਾ ਨਹੀਂ ਹੈ। ਇਸਦਾ ਮਤਲਬ ਸਹੀ ਭਾਸ਼ਾ ਹੈ ਜਿਸ ਵਿੱਚੋਂ ਕਾਰਪੋਰੇਟ ਫਾਲਤੂ ਸ਼ਬਦਾਂ ਨੂੰ ਹਟਾ ਦਿੱਤਾ ਗਿਆ ਹੋਵੇ।
ਅਜਿਹਾ ਢਾਂਚਾ ਜੋ ਅਸਲ ਵਿੱਚ ਮਦਦ ਕਰਦਾ ਹੈ
ਇੱਕ ਅਸੰਗਠਿਤ ਮੈਨੂਅਲ (manual) ਨਾ ਹੋਣ ਨਾਲੋਂ ਵੀ ਜ਼ਿਆਦਾ ਸਮਾਂ ਬਰਬਾਦ ਕਰਦਾ ਹੈ। ਆਪਣੇ ਦਸਤਾਵੇਜ਼ ਨੂੰ ਇੱਕ ਫਨਲ (funnel) ਵਜੋਂ ਸਮਝੋ। ਸਭ ਤੋਂ ਉੱਪਰ, ਇੱਕ ਛੋਟਾ ਜਿਹਾ ਓਵਰਵਿਊ (overview) ਰੱਖੋ ਜੋ ਦੱਸੇ ਕਿ ਪ੍ਰੋਜੈਕਟ ਕੀ ਕਰਦਾ ਹੈ ਅਤੇ ਕਿਸ ਨੂੰ ਇਸ ਬਾਰੇ ਜਾਣਨਾ ਚਾਹੀਦਾ ਹੈ। ਇਸ ਤੋਂ ਬਾਅਦ ਇੰਸਟਾਲੇਸ਼ਨ ਹਦਾਇਤਾਂ ਦਿਓ ਜੋ ਪਾਠਕ ਦੇ ਲੋਕਲ ਸੈੱਟਅੱਪ ਬਾਰੇ ਕੁਝ ਵੀ ਨਹੀਂ ਮੰਨਦੀਆਂ। ਫਿਰ ਟਿਊਟੋਰਿਅਲਸ (tutorials) ਜੋ ਸ਼ੁਰੂ ਤੋਂ ਅੰਤ ਤੱਕ ਪੂਰੇ ਅਤੇ ਅਸਲੀ ਦ੍ਰਿਸ਼ਜੋ (scenarios) ਰਾਹੀਂ ਲੈ ਕੇ ਜਾਂਦੇ ਹਨ। ਇਸ ਤੋਂ ਬਾਅਦ API ਰੈਫਰੈਂਸ (references) ਆਉਂਦੇ ਹਨ। ਇਹ ਵਿਸਤ੍ਰਿਤ ਹੋਣੇ ਚਾਹੀਦੇ ਹਨ ਪਰ ਸਕੈਨ ਕਰਨ ਯੋਗ ਹੋਣੇ ਚਾਹੀਦੇ ਹਨ, ਜਿਨ੍ਹਾਂ ਨੂੰ ਅਲਫਾਬੇਟਿਕਲ ਕ੍ਰਮ ਵਿੱਚ ਰੱਖਣ ਦੀ ਬਜਾਏ ਰਿਸੋਰਸ ਜਾਂ ਫੰਕਸ਼ਨ ਦੁਆਰਾ ਸਮੂਹਬੱਧ ਕੀਤਾ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ। ਅੰਤ ਵਿੱਚ, ਟਰਬਲਸ਼ੂਟਿੰਗ ਗਾਈਡਸ (troubleshooting guides) ਰੱਖੋ ਜੋ ਖਾਸ ਲੱਛਣਾਂ ਨੂੰ ਹੱਲ ਕਰਦੀਆਂ ਹਨ। "Connection refused" ਮਿਲਣ ਵਾਲੇ ਯੂਜ਼ਰ ਨੂੰ "Permission denied" ਦੇਖਣ ਵਾਲੇ ਯੂਜ਼ਰ ਨਾਲੋਂ ਵੱਖਰਾ ਜਵਾਬ ਚਾਹੀਦਾ ਹੁੰਦਾ ਹੈ। ਐਰਰਸ (errors) ਨੂੰ ਸੁਨੇਹੇ ਜਾਂ ਸੰਦਰਭ (context) ਅਨੁਸਾਰ ਸਮੂਹਬੱਧ ਕਰੋ, ਨਾ ਕਿ ਅਮੂਰਤ ਸ਼੍ਰੇਣੀ (abstract category) ਅਨੁਸਾਰ।
ਲਿਸਟਾਂ (lists) ਅਤੇ ਕੋਡ ਬਲਾਕਸ (code blocks) ਸੰਘਣੇ ਟੈਕਸਟ ਨੂੰ ਤੋੜਦੇ ਹਨ ਅਤੇ ਪਾਠਕਾਂ ਨੂੰ ਉਹਨਾਂ ਸਹੀ ਕਮਾਂਡਾਂ ਨੂੰ ਲੱਭਣ ਵਿੱਚ ਮਦਦ ਕਰਦੇ ਹਨ ਜਿਨ੍ਹਾਂ ਦੀ ਉਹਨਾਂ ਨੂੰ ਲੋੜ ਹੈ। ਇੱਕ ਸਹੀ ਜਗ੍ਹਾ 'ਤੇ ਲਗਾਈ ਗਈ ਬੁਲੇਟ ਲਿਸਟ ਉਲਝਣ ਵਾਲੇ ਪੈਰੇ ਨੂੰ ਕਾਰਵਾਈਆਂ ਦੇ ਕ੍ਰਮ ਵਿੱਚ ਬਦਲ ਸਕਦੀ ਹੈ।
ਸਿਰਫ਼ ਦੱਸੋ ਨਾ, ਦਿਖਾਓ
ਅਮੂਰਤ ਵਿਆਖਿਆਵਾਂ ਯੂਜ਼ਰਸ ਨੂੰ ਨਿਰਾਸ਼ ਕਰਦੀਆਂ ਹਨ। ਜੇਕਰ ਤੁਸੀਂ ਕਿਸੇ ਟੂਲ ਨੂੰ ਕੌਂਫਿਗਰ ਕਰਨ ਦਾ ਤਰੀਕਾ ਦੱਸਦੇ ਹੋ, ਤਾਂ ਫਾਈਲ ਦੀ ਸਹੀ ਸਮੱਗਰੀ ਦਿਖਾਓ। ਇੰਸਟਾਲੇਸ਼ਨ, ਇਨੀਸ਼ੀਅਲਾਈਜ਼ੇਸ਼ਨ, ਅਤੇ ਆਮ ਕੌਂਫਿਗਰੇਸ਼ਨਾਂ ਲਈ ਕੋਡ ਸਨਿਪੇਟਸ (code snippets) ਪ੍ਰਦਾਨ ਕਰੋ। ਸੈਂਪਲ ਇਨਪੁੱਟਸ (inputs) ਅਤੇ ਉਮੀਦ ਕੀਤੇ ਆਊਟਪੁੱਟਸ (outputs) ਨੂੰ ਆਮ੍ਹne-ਸਾਹਮਣੇ ਦਿਖਾਓ। ਜੇਕਰ ਤੁਹਾਡਾ API JSON ਰਿਟਰਨ ਕਰਦਾ ਹੈ, ਤਾਂ JSON ਦਿਖਾਓ। ਜੇਕਰ ਕੋਈ CLI ਟੂਲ ਟੈਬੂਲਰ ਆਊਟਪੁੱਟ (tabular output) ਦਿੰਦਾ ਹੈ, ਤਾਂ ਟੇਬਲ ਦਿਖਾਓ। ਕਦੇ ਵੀ ਇਹ ਵਿਸ਼ਵਾਸ ਨਾ ਕਰੋ ਕਿ ਕਿਸੇ ਵਰਕਫਲੋ (workflow) ਦਾ ਵੇਰਵਾ ਇੱਕ ਪ੍ਰਦਰਸ਼ਨ ਦੇ ਬਰਾਬਰ ਹੈ।
ਸਭ ਤੋਂ ਮਹੱਤਵਪੂਰਨ ਗੱਲ ਇਹ ਹੈ ਕਿ ਪ੍ਰਕਾਸ਼ਿਤ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ ਹਰ ਉਦਾਹਰਣ ਨੂੰ ਇੱਕ ਸਾਫ਼ ਵਾਤਾਵਰਣ (environment)