ತಾಂತ್ರಿಕ ದಾಖಲಾತಿ (Technical documentation) ಎಂಬುದು ಕೋಡ್ ಕಾಂಪೈಲ್ ಆದ ನಂತರ ಮುಗಿಸುವ ಪೂರಕ ಕೆಲಸವಲ್ಲ. ಇದು ಪ್ರತಿ ಸಾಫ್ಟ್ವೇರ್ ಪ್ರಾಜೆಕ್ಟ್ನ ಕೇಂದ್ರಬಿಂದುವಾಗಿದೆ; ಒಬ್ಬ ಹೊಸ ಡೆವಲಪರ್ ತನ್ನ ಮೊದಲ ದಿನದಲ್ಲೇ ಬಗ್ ಅನ್ನು ಸರಿಪಡಿಸಬಲ್ಲನೇ ಅಥವಾ ಗೊಂದಲಕ್ಕೊಳಗಾದ ಬಳಕೆದಾರರು ಐದು ನಿಮಿಷಗಳಲ್ಲಿ ನಿಮ್ಮ ಉತ್ಪನ್ನವನ್ನು ಕೈಬಿಡುತ್ತಾರೆಯೇ ಎಂಬುದನ್ನು ಇದು ನಿರ್ಧರಿಸುತ್ತದೆ. ಉತ್ತಮ ದಾಖಲಾತಿಯು ಬಳಕೆದಾರರು ನೈಜ ಕಾರ್ಯಗಳನ್ನು ಪೂರ್ಣಗೊಳಿಸಲು ಸಹಾಯ ಮಾಡುತ್ತದೆ. ಭವಿಷ್ಯದ ನಿರ್ವಹಕರು (maintainers) ಒಂದು ಮಾಡ್ಯೂಲ್ ಏಕೆ ಅಸ್ತಿತ್ವದಲ್ಲಿದೆ ಮತ್ತು ಎಲ್ಲವನ್ನೂ ಹಾಳು ಮಾಡದೆಯೇ ಅದನ್ನು ಹೇಗೆ ಬದಲಾಯಿಸಬೇಕು ಎಂಬುದನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳಲು ಇದು ಸಹಾಯ ಮಾಡುತ್ತದೆ. ಆದರೂ ಅನೇಕ ತಂಡಗಳು ದಾಖಲಾತಿಯನ್ನು ಒಂದು ನಂತರದ ಕೆಲಸವಾಗಿ, ಅವಸರದಲ್ಲಿ ಸಿದ್ಧಪಡಿಸಿದ README ಅಥವಾ ಕೊಳೆತು ಹೋಗುವ ವಿಕಿ (wiki) ಪುಟವಾಗಿ ಪರಿಗಣಿಸುತ್ತವೆ. ನಿಜವಾಗಿಯೂ ಉಪಯುಕ್ತವಾದ ದಾಖಲಾತಿಯನ್ನು ಬರೆಯುವುದು ನೀವು ಉದ್ದೇಶಪೂರ್ವಕವಾಗಿ ಸುಧಾರಿಸಿಕೊಳ್ಳಬಹುದಾದ ಒಂದು ಕೌಶಲವಾಗಿದೆ.
ಬರೆಯುವ ಮೊದಲು ನಿಮ್ಮ ಓದುಗರನ್ನು ತಿಳಿಯಿರಿ
ನೀವು ಒಂದು ಹೆಡಿಂಗ್ ಬರೆಯುವ ಮೊದಲೇ, ಇದನ್ನು ಓದುವವರು ಯಾರು ಎಂಬುದನ್ನು ನಿರ್ಧರಿಸಿ. ಕನೆಕ್ಷನ್ ಪೂಲ್ ಸೆಟ್ಟಿಂಗ್ಗಳಿಗಾಗಿ ಹುಡುಕುತ್ತಿರುವ ಡೇಟಾಬೇಸ್ ಅಡ್ಮಿನಿಸ್ಟ್ರೇಟರ್ ಮತ್ತು React component props ಹುಡುಕುತ್ತಿರುವ ಫ್ರಂಟ್-ಎಂಡ್ ಡೆವಲಪರ್ ನಡುವೆ ಯಾವುದೇ ಸಾಮ್ಯತೆ ಇರುವುದಿಲ್ಲ. ಅಂತಿಮ ಬಳಕೆದಾರರಿಗೆ (End-users) ನಂಬರ್ ಮಾಡಲಾದ ಹಂತಗಳು ಮತ್ತು ಸ್ಕ್ರೀನ್ಶಾಟ್ಗಳು ಬೇಕೇ ಹೊರತು ಆರ್ಕಿಟೆಕ್ಚರ್ ಡಯಾಗ್ರಾಮ್ಗಳಲ್ಲ. ಅವರು ಹೇಗೆ PDF ಅನ್ನು ಎಕ್ಸ್ಪೋರ್ಟ್ ಮಾಡಬೇಕು ಎಂಬುದನ್ನು ತಿಳಿಯಲು ಬಯಸುತ್ತಾರೆಯೇ ಹೊರತು ರೆಂಡರಿಂಗ್ ಪೈಪ್ಲೈನ್ ಹೇಗೆ ಕೆಲಸ ಮಾಡುತ್ತದೆ ಎಂಬುದನ್ನಲ್ಲ. ನಿಮ್ಮ ಲೈಬ್ರರಿಯನ್ನು ಇಂಟಿಗ್ರೇಟ್ ಮಾಡುವ ಡೆವಲಪರ್ಗಳಿಗೆ ನಿಖರವಾದ function signatures, error codes ಮತ್ತು ಕಾಪಿ-ಪೇಸ್ಟ್ ಮಾಡಬಹುದಾದ ಸ್ನಿಪ್ಪೆಟ್ಗಳು ಬೇಕಾಗುತ್ತವೆ. ಸಿಸ್ಟಮ್ ಅಡ್ಮಿನಿಸ್ಟ್ರೇಟರ್ಗಳಿಗೆ ಇನ್ಸ್ಟಾಲೇಶನ್ ಪೂರ್ವಪರಿquisiteಗಳು, ಎನ್ವಿರಾನ್ಮೆಂಟ್ ವೇರಿಯೇಬಲ್ಗಳು ಮತ್ತು ಸಾಮಾನ್ಯ ವೈಫಲ್ಯಗಳಿಂದ ಪ್ರಾರಂಭವಾಗುವ ಟ್ರಬಲ್ಶೂಟಿಂಗ್ ಹರಿವುಗಳು ಬೇಕಾಗುತ್ತವೆ.
ನೀವು ಒಂದೇ ಪ್ಯಾರಾಗ್ರಾಫ್ನಲ್ಲಿ ಈ ಮೂರೂ ಗುಂಪುಗಳಿಗೆ ಸೇವೆ ನೀಡಲು ಪ್ರಯತ್ನಿಸಿದರೆ, ಎಲ್ಲರೂ ಸೋಲುತ್ತಾರೆ. ಪ್ರತ್ಯೇಕ ಮಾರ್ಗಗಳನ್ನು ರಚಿಸಿ. ಒಂದೇ ಪುಟವನ್ನೇ "ಆಪರೇಟರ್ಗಳಿಗಾಗಿ" ಮತ್ತು "ಕ್ಲೈಂಟ್ ಡೆವಲಪರ್ಗಳಿಗಾಗಿ" ಎಂಬ ಸ್ಪಷ್ಟ ಹೆಡಿಂಗ್ಗಳೊಂದಿಗೆ ವಿಂಗಡಿಸಬಹುದು. "ಈ ಪ್ಯಾರಾಗ್ರಾಫ್ ನನಗಾಗಿಯೇ ಇದೆ?" ಎಂದು ಕೇಳುವ ಮಾನಸಿಕ ಗೊಂದಲವನ್ನು ಹೋಗಲಾಡಿಸುವುದು ಇದರ ಗುರಿಯಾಗಲಿ.
ಅನಗತ್ಯ ವಿಷಯಗಳನ್ನು ಕಡಿತಗೊಳಿಸಿ
ಸ್ಪಷ್ಟತೆಯು ಚಾತುರ್ಯಕ್ಕಿಂತ ಮಿಗಿಲಾದುದು. ಸಣ್ಣ ವಾಕ್ಯಗಳನ್ನು ಬಳಸಿ. ಕರ್ತರಿ ಪ್ರಯೋಗವನ್ನು (active voice) ಬಳಸಿ. "The database should be initialized by the user" ಎನ್ನುವುದಕ್ಕಿಂತ "Initialize the database" ಎಂಬುದು ಹೆಚ್ಚು ಸ್ಪಷ್ಟವಾಗಿದೆ. ನೀವು "idempotency" ಅಥವಾ "serialization" ನಂತಹ ತಾಂತ್ರಿಕ ಪದವನ್ನು ಬಳಸಬೇಕಾದಾಗ, ಅದನ್ನು ಒಳಗೆ ವ್ಯಾಖ್ಯಾನಿಸಿ ಅಥವಾ ಗ್ಲೋಸರಿ (glossary) ಗೆ ಲಿಂಕ್ ಮಾಡಿ. ಮೊದಲೇ ತಿಳಿದಿರುವ ಜ್ಞಾನವನ್ನು ಅವಲಂಬಿಸಬೇಡಿ.
ಒಂದು ಪ್ರಾಯೋಗಿಕ ಪರೀಕ್ಷೆ: ನಿಮ್ಮ ಪ್ಯಾರಾಗ್ರಾಫ್ ಅನ್ನು ಜೋರಾಗಿ ಓದಿ ನೋಡಿ. ನಿಮಗೆ ಉಸಿರಾಡಲು ಕಷ್ಟವಾದರೆ, ಆ ವಾಕ್ಯವು ತುಂಬಾ ಉದ್ದವಾಗಿದೆ ಎಂದರ್ಥ. ಇನ್ನೊಂದು ಪರೀಕ್ಷೆ: ಅಲಂಕಾರಿಕ ಕ್ರಿಯಾಪದಗಳ ಬದಲಿಗೆ ಸರಳ ಕ್ರಿಯಾಪದಗಳನ್ನು ಬಳಸಿ. ಒಂದು ವೇಳೆ "utilize the API" ಎಂಬ ಪದವನ್ನು ಅರ್ಥ ಬದಲಾಗದಂತೆ "use the API" ಎಂದು ಬದಲಾಯಿಸಬಹುದಾದರೆ, ಖಂಡಿತವಾಗಿಯೂ ಬದಲಾಯಿಸಿ. ಸರಳ ಭಾಷೆ ಎಂದರೆ ವಿಷಯವನ್ನು ಕೀಳಾಗಿ ಹೇಳುವುದು ಎಂದಲ್ಲ; ಅದರರ್ಥ ಕಾರ್ಪೊರೇಟ್ ಅತಿರೇಕವಿಲ್ಲದ ನಿಖರವಾದ ಭಾಷೆ ಎಂದರ್ಥ.
ನಿಜವಾಗಿಯೂ ಸಹಾಯ ಮಾಡುವ ರಚನೆ
ಅಸ್ತವ್ಯಸ್ತವಾದ ಮ್ಯಾನುಯಲ್ ಇಲ್ಲದ ಮ್ಯಾನುಯಲ್ಗಿಂತಲೂ ಹೆಚ್ಚು ಸಮಯವನ್ನು ವ್ಯರ್ಥ ಮಾಡುತ್ತದೆ. ನಿಮ್ಮ ದಾಖಲಾತಿಯನ್ನು ಒಂದು ಫನಲ್ (funnel) ಎಂದು ಭಾವಿಸಿ. ಮೇಲ್ಭಾಗದಲ್ಲಿ, ಪ್ರಾಜೆಕ್ಟ್ ಏನು ಮಾಡುತ್ತದೆ ಮತ್ತು ಯಾರು ಇದನ್ನು ಗಮನಿಸಬೇಕು ಎಂಬುದನ್ನು ವಿವರಿಸುವ ಸಂಕ್ಷಿಪ್ತ ಅವಲೋಕನವನ್ನು (overview) ಇರಿಸಿ. ನಂತರ, ಓದುಗರ ಸ್ಥಳೀಯ ಸೆಟಪ್ ಬಗ್ಗೆ ಏನನ್ನೂ ಊಹಿಸದೆ ಇನ್ಸ್ಟಾಲೇಶನ್ ಸೂಚನೆಗಳನ್ನು ನೀಡಿ. ನಂತರ, ಆರಂಭದಿಂದ ಅಂತ್ಯದವರೆಗೆ ಸಂಪೂರ್ಣ ಮತ್ತು ವಾಸ್ತವಿಕ ಸನ್ನಿವೇಶಗಳನ್ನು ವಿವರಿಸುವ ಟ್ಯುಟೋರಿಯಲ್ಗಳನ್ನು ಸೇರಿಸಿ. ನಂತರ API ರೆಫರೆನ್ಸ್ ಬರಲಿ. ಇವು ಸಮಗ್ರವಾಗಿರಬೇಕು ಆದರೆ ಸುಲಭವಾಗಿ ಸ್ಕ್ಯಾನ್ ಮಾಡುವಂತಿರಬೇಕು; ಅಕ್ಷರಮಾಲೆಯ ಕ್ರಮದಲ್ಲಿ ಹಾಕುವ ಬದಲು ಸಂಪನ್ಮೂಲ ಅಥವಾ ಫಂಕ್ಷನ್ ಮೂಲಕ ಗುಂಪು ಮಾಡಿ. ಕೊನೆಯದಾಗಿ, ನಿರ್ದಿಷ್ಟ ಸಮಸ್ಯೆಗಳನ್ನು ಪರಿಹರಿಸುವ ಟ್ರಬಲ್ಶೂಟಿಂಗ್ ಗೈಡ್ಗಳನ್ನು ಇರಿಸಿ. "Connection refused" ಎಂಬ ಸಂದೇಶ ಪಡೆಯುವ ಬಳಕೆದಾರರಿಗೆ ಮತ್ತು "Permission denied" ಎಂಬ ಸಂದೇಶ ಕಾಣಿಸುವ ಬಳಕೆದಾರರಿಗೆ ಬೇರೆ ಬೇರೆ ಉತ್ತರಗಳು ಬೇಕಾಗುತ್ತವೆ. ದೋಷಗಳನ್ನು (errors) ಅಮೂರ್ತ ವರ್ಗಗಳ ಬದಲು ಸಂದೇಶ ಅಥವಾ ಸಂದರ್ಭದ ಆಧಾರದ ಮೇಲೆ ಗುಂಪು ಮಾಡಿ.
ಲಿಸ್ಟ್ಗಳು ಮತ್ತು ಕೋಡ್ ಬ್ಲಾಕ್ಗಳು ದಟ್ಟವಾದ ಪಠ್ಯವನ್ನು ವಿಭಜಿಸುತ್ತವೆ ಮತ್ತು ಓದುಗರಿಗೆ ಬೇಕಾದ ನಿಖರವಾದ ಕಮಾಂಡ್ ಅನ್ನು ಹುಡುಕಲು ಸುಲಭವಾಗುವಂತೆ ಮಾಡುತ್ತವೆ. ಸರಿಯಾಗಿ ಬಳಸಲಾದ ಬುಲೆಟ್ ಲಿಸ್ಟ್ ಗೊಂದಲಮಯ ಪ್ಯಾರಾಗ್ರಾಫ್ ಅನ್ನು ಕ್ರಮಬದ್ಧವಾದ ಕ್ರಮಗಳಾಗಿ ಪರಿವರ್ತಿಸಬಹುದು.
ಕೇವಲ ಹೇಳಬೇಡಿ, ತೋರಿಸಿ
ಅಮೂರ್ತ ವಿವರಣೆಗಳು (Abstract explanations) ಬಳಕೆದಾರರನ್ನು ವಿಚಲಿತಗೊಳಿಸುತ್ತವೆ. ನೀವು ಒಂದು ಟೂಲ್ ಅನ್ನು ಹೇಗೆ ಕಾನ್ಫಿಗರ್ ಮಾಡಬೇಕೆಂದು ವಿವರಿಸುತ್ತಿದ್ದರೆ, ಅದರ ನಿಖರವಾದ ಫೈಲ್ ವಿಷಯವನ್ನು ತೋರಿಸಿ. ಇನ್ಸ್ಟಾಲೇಶನ್, ಇನಿಶಿಯಲೈಸೇಶನ್ ಮತ್ತು ಸಾಮಾನ್ಯ ಕಾನ್ಫಿಗರೇಶನ್ಗಳಿಗಾಗಿ ಕೋಡ್ ಸ್ನಿಪ್ಪೆಟ್ಗಳನ್ನು ಒದಗಿಸಿ. ಸ್ಯಾಂಪಲ್ ಇನ್ಪುಟ್ಗಳು ಮತ್ತು ನಿರೀಕ್ಷಿತ ಔಟ್ಪುಟ್ಗಳನ್ನು ಪಕ್ಕಪಕ್ಕದಲ್ಲಿ ತೋರಿಸಿ. ನಿಮ್ಮ APIು JSON ಅನ್ನು ರಿಟರ್ನ್ ಮಾಡಿದರೆ, ಆ JSON ಅನ್ನು ತೋರಿಸಿ. ನಿಮ್ಮ CLI ಟೂಲ್ ಟ್ಯಾಬುಲರ್ ಔಟ್ಪುಟ್ ನೀಡಿದರೆ, ಆ ಟೇಬಲ್ ಅನ್ನು ತೋರಿಸಿ. ಕೆಲಸದ ಹರಿವಿನ (workflow) ವಿವರಣೆಯು ಪ್ರಾಯೋಗಿಕ ಪ್ರದರ್ಶನಕ್ಕೆ ಸಮಾನ ಎಂಬ ನಂಬಿಕೆಯನ್ನು ಎಂದಿಗೂ ಇಟ್ಟುಕೊಳ್ಳಬೇಡಿ.
ಅತಿ ಮುಖ್ಯವಾಗಿ, ನೀವು ಪ್ರಕಟಿಸುವ ಮೊದಲು ಪ್ರತಿಯೊಂದು ಉದಾಹರಣೆಯನ್ನು ಸ್ವಚ್ಛವಾದ ಎನ್ವಿರಾನ್ಮೆಂಟ್ನಲ್ಲಿ ಪರೀಕ್ಷಿಸಿ. ನಿಮ್ಮ ಸ್ವಂತ ಸ್ನಿಪ್ಪೆಟ್ ಅನ್ನು ಹೊಸ ಕಂಟೇನರ್ ಅಥವಾ ವರ್ಚುವಲ್ ಮೆಷಿನ್ನಲ್ಲಿ ಬಳಸಿ ನೋಡಿ. ನೀವು ಯಾವುದಾದರೂ ಡಿಪೆಂಡೆನ್ಸಿಯನ್ನು (dependency) ಉಲ್ಲೇಖಿಸಲು ಮರೆತಿದ್ದರಿಂದ ಅದು ವಿಫಲವಾದರೆ, ನೀವು ದೊಡ್ಡ ಮಟ್ಟದ ಸಮಸ್ಯೆಗಳಿಂದ ನಿಮ್ಮನ್ನು ನೀವು ರಕ್ಷಿಸಿಕೊಂಡಿದ್ದೀರಿ ಎಂದರ್ಥ. ನೈಜ ಉದಾಹರಣೆಗಳು ತಾಂತ್ರಿಕ ಬರಹದಲ್ಲಿ ಅತ್ಯುತ್ತಮವಾದ ප්රතිಫಲವನ್ನು ನೀಡುತ್ತವೆ ಏಕೆಂದರೆ ಅವು ಅನಿಶ್ಚಿತತೆಯನ್ನು ಕ್ರಿಯೆಯಾಗಿ ಬದಲಾಯಿಸುತ್ತವೆ.
ಅದನ್ನು ಜೀವಂತವಾಗಿಡಿ
ಕೋಡ್ಗಿಂತ ದಾಖಲಾತಿಯು ವೇಗವಾಗಿ ಹಳೆಯದಾಗುತ್ತದೆ. ಒಂದು ಮೆಥಡ್ ಸಿಗ್ನೇಚರ್ ಬದಲಾಗುತ್ತದೆ, ಡಿಫಾಲ್ಟ್ ಪೋರ್ಟ್ ಬದಲಾಗುತ್ತದೆ, ಒಂದು ಡಿಪೆಂಡೆನ್ಸಿ ಬದಲಾಗುತ್ತದೆ ಮತ್ತು ಇದ್ದಕ್ಕಿದ್ದಂತೆ ನಿಮ್ಮ ಸೂಚನೆಗಳು ವ್ಯರ್ಥವಾಗುತ್ತವೆ...