개발자들이 대부분 코드 품질은 향상 시키고 구조 개선 등 많은 노력을 하지만 그에 반해 글쓰기는 소홀히 하는 경우가 많습니다. 그리고 대부분의 기술 문서들이 개발 이후에 작성되고 있고 충분한 고민과 시간을 사용하지 못합니다.. 그래서 기술 문서를 읽고도 새로운 커뮤니케이션 비용이 들어가는 경우가 빈번하게 발생하고 있습니다. 그래서 해당 문서에서는 기술 문서를 조금 더 효과적으로 쓰는 방법을 공유하고자 합니다.
테크니컬 라이팅(Technical writing)은 좁은 의미로는 과학 기술 정보를 정확하고 효과적으로 전달하기 위한 문서 작성 기술을 뜻합니다. 넓은 의미로는 모든 유형의 글을 보다 알기 쉽게 전달하는 글쓰기를 통칭하기도 합니다. 문예적인 글(소설, 수필 등)과 같은 글쓰기를 제외한 모든 유형의 글쓰기에서 그 뜻을 분명하고 쉽게 독자들에게 전달하는 것을 목표로 갖고 있습니다. 즉, 개발자 중심의 기술 관련 용어 혹은 설명을 독자가 이해하기 쉽게 콘텐츠를 가공, 관리하며 문서화 작업을 계획하고 수행하는 것을 말합니다.
글쓰기에서 필수로 고려해야 할 사항은 독자를 파악하는 것입니다. 작성한 문서를 가장 많이 읽고 사용할 사람은 누구인지, 그 사람이 해당 문서의 기술, 내용에 대한 기본 지식은 얼마나 있는지 수준을 명확하고 알고 작성을 해야 합니다. 만약 개발자가 본다면 기술적인 용어들을 섞어서 사용해도 상관없겠지만 그게 아니라 개발자가 아닌 사람도 해당 문서를 읽는 경우라면 최대한 쉽게 풀어서 글을 작성해야 합니다.
테크니컬 라이팅은 큰 범주에서 보면 글쓰기의 한 부분에 속합니다. 하지만, 본인의 창작이나 생각을 제외한 사실만을 서술하는 것을 목표로 하며 수식어 및 모호한 표현을 최대한 지양해야 합니다.
테크니컬 라이팅의 목표는 독자가 해당 문서의 기술을 더 빠르게 효과적을 익힐 수 있게 돕는 것입니다. 그래서 아래의 원칙들을 따라 작성하는 것이 필요합니다.
테크니컬 라이팅의 4대 원칙은 명확성, 간결성, 정확성, 일관성입니다.
명확한 글이란 핵심어나 핵심 문장을 모호하게 사용하지 않고, 대상 독자가 기술문서를 읽을 때 내용의 모호함 혹은 혼란 없이 한번에 이해할 수 있는 글입니다.
명확성이 모호해지는 대부분의 경우는 대상 독자를 제대로 파악하지 못해서 발생합니다. 명확성 예시처럼 본론인 3번을 먼저 설명하고 1번으로 넘어가거나, 사전 작업에 대한 언급을 생략하고 본론을 설명하는 경우가 많습니다. 독자가 구성원 내의 사람인 경우 이런일이 빈번하게 발생합니다. 하지만 사전지식을 알고 있을거라 생각하는건 지극히 주관적인 관점일 수 있기 때문에 사전지식을 충분히 설명한 이후 본론에 대한 내용을 작성해야합니다.
간결성이란 특정 독자가 기술적인 내용을 신속하고 정확하게 이해할 수 있도록 미사여구나 감탄사 등을 사용하지 않고, 간단하고 쉬운 단어와 간결한 문장을 사용하는 것입니다.
Before
모노레포 형식으로 분리 될 예정으로 각 pt 별로 Sentry 프로젝트를 생성하여 각각pt 별로 이슈 모니터링을 하도록 함
After
모노레포 방식으로 분리할 예정입니다.
각 PT별 센트리(Sentry) 프로젝트 생성 및 이슈 모니터링이 가능하도록 구성했습니다.
정확성이란 독자가 필요로 하는 정보를 기술적 오류 없이 정확하게 제공하는 것을 말합니다. 명확성, 간결성보다 훨씬 중요도가 높은 항목으로, 정확성이 없다면 독자가 아무리 시간을 들여서 읽는다 해도 문서를 파악할 수 없게 됩니다.
문서의 용어, 표현, 그리고 어조 등을 일관성 있게 사용하는 것을 말합니다. 문서 뿐만이 아니라 일반적인 커뮤니케이션에서도 중요한 원칙입니다.
예시 – 견적 분석 페이지, 금융사 선택 페이지
두 페이지는 같은 페이지인데 기획에 따라 용어가 섞여서 쓰이기 시작하면서 각각 다른 이름으로 불리는 경우가 있는데 용어는 일관성 있게 유지하기 위해 같은 명칭으로 사용해야 합니다.
어렵고 딱딱한 용어들을 최대한 쉽고 친절하게 고쳐쓰는 것을 말합니다. 전문 용어는 꼭 필요할 때 사용합니다. 문서를 읽는 모든 사용자가 전문 용어에 대해 알지 않습니다. 전문 용어를 사용하는 경우 그 용어를 잘 설명해주고 일관성있게 유지해야합니다.
Technical Writing의 프로세스로 5단계를 따릅니다.
첫 번째 단계는 문서 기획 단계로, 프로젝트를 시작하는 미팅에서 논의되는 것이 가장 이상적입니다.
두 번째 단계는 목차 구조화 단계입니다. 기획 단계에서 수집한 정보들을 구조화하여 문서의 목차를 구성하는 단계입니다. 참조 문서들을 잘 분석하고 가독성, 독자의 편의성 등을 고려해야 합니다. 문서의 용도 별 템플릿, 스타일, 목차 구성 가이드를 만드는 게 가장 효과적입니다.
세 번째 단계는 초안을 작성하고 다듬는 단계입니다. 이 단계에서는 전달하고자 하는 내용을 모두 넣는 것에 집중해서 초안을 작성합니다. 국내의 경우 문서화의 중요성에 대한 인지도가 상대적으로 떨어지기 때문에, 문서 작업은 개발과 별개인 부차적 업무로 생각되는 경우가 많습니다. 그래서 개발이 완료된 이후에 문서 작성을 시작하면 대부분 그 이후 새로운 업무에 시간을 뺏기면서 문서 작성에 충분한 시간을 투입하지 못하게 되고 충분히 검토되지 않은 문서가 만들어지기 쉽습니다.
이러한 문제는 문서 작성에 얼마나 많은 시간이 쓰이는지 파악하지 못해서 생기는 이슈인데 ISO/IEC 표준에 따르면 문서 한 페이지의 초안을 작성할 때 1시간이 소요됩니다. 30장의 문서를 작성하기 위해서는 30시간이 필요합니다. 즉, 4일을 온전히 문서 작업에 몰두해야 한다는 계산이 나오는데 이러한 시간들은 현실적으로 어렵습니다.
네 번째 단계는 리뷰 단계로 작성된 문서를 기술적인 측면, 스타일적인 측면에서 확인하는 단계입니다. 기술적인 리뷰에서는 문서의 기술적인 내용에 오류가 없는 지에 맞춰서 진행되고, 스타일적인 측면에서는 문서의 구조, 문법, 맞춤법 등에 오류가 없는 지에 맞춰서 진행됩니다.
마지막 단계는 최종 문서를 독자에게 전달하기 위한 배포 단계입니다. 이 단계에서는 기획 단계에서 정한 발행일 및 파일 형식에 맞게 구성해서 배포해야 합니다.
https://it-ist.tistory.com/274
https://devocean.sk.com/search/techBoardDetail.do?ID=165343
https://tech.kakaoenterprise.com/102
https://tech-kakaoenterprise.tistory.com/105
https://toss.tech/article/tech-writer-1
https://insight.infograb.net/blog/2023/03/30/technical-writing-guide/