요즘은 테크니컬 라이터 분들이 기술 블로그를 관리하시기도 하는군요!
넷마블의 기술블로그를 담당하는 테크니컬 라이터의 회고록을 보면서, 개발자의 글쓰기에 관한 인사이트를 얻을 수 있었습니다.
좋은 개발 문서를 작성하려면 어떻게 해야할지 그 노하우가 담긴 글인데요. 개인 기술 블로그를 운영하거나, 회사에서 기술 문서를 작성할 때 꼭 참고해보면 좋은 팁인것 같아 정리해봤습니다.
✍🏻 기술 문서 작성하기 팁
• 개발 문서를 보는 대상에게 가장 익숙한 용어로 통일하는 것을 권장.
• 샘플 코드나 명령어 등은 영어 그대로 작성한다.
• 알파벳 철자가 많은 영단어는 한글로 음차해서 표현한다. (ex. StackOverFlow = 스택오버플로우)
• 외래어 표기법이 헷갈릴 때는 표준국어대사전과 우리말샘에서 확인하기!
• 무엇을 쓸지 키워드나 제목을 나열해 목차(ToC)를 만들어볼 것
• 예제나 샘플 코드를 먼저 정리하고 작성하기
• 명령어 기반 가이드는 명령어와 결과를 정리하면 좋다.
• 원인과 결과 관계가 맞는 논리적인 글로 작성하도록 노력한다.
• 퇴고 (글쓰기의 QA 과정)
👩🏻💻 좋은 문서 작성 도구 기준
• 내가 글쓰기 편한 도구
• 웹페이지 변환에 용이하도록 HTML, 마크다운으로 내보내기 가능한 도구
• 버전 관리가 가능한 도구
• 글쓴이의 톱 픽 👉🏻 Visual Studio Code