3단계: 쓰기

안녕하세요. 테크니컬 라이터 유경미입니다.

오늘은 드디어 대망의 쓰기 단계를 이야기하는 날입니다! 제가 지난번부터 '대망(待望, 기다리고 바람)의'라는 수식어를 쓰고 있는데, 아무래도 글쓰기의 메인은 쓰기가 아니겠어요?

그래서 쓴 거지, 대망(大亡, 크게 망하다)의 중의적 의미라거나 그런 건 아니에요.

아니죠, 당연히. 아닐 거예요...... へ[ ᴼ ▃ ᴼ ]_/¯

하핫, 그럼 할 수 있다(!!!)라는 자신감으로 시작해 볼까요?

'기술 글'쓰기, 어떤 글쓰기인가요?

지금까지 기술 글쓰기를 각 단계마다 조금씩 다르게 정의해왔는데요.

먼저 '기획하기' 단계에서는 기술 글쓰기를 '수요가 있는 글쓰기'로 보고, 그 수요를 정확히 파악하기 위해 독자와 목적을 분석해야 한다고 말씀드렸죠.

또 '뼈대 잡기' 단계에서는 '정형화된 패턴을 가진 글쓰기'로 보고, 그 패턴을 이용해 글의 흐름을 구성하는 방법을 알아봤어요.

이제 '쓰기' 단계에서는, 기술 글쓰기를 '객관적이고 효율적인 글쓰기'라고 정의해보려고 합니다. 그런 글쓰기를 하려면, 다음 두 질문을 항상 떠올려야 해요.

이 질문들을 마음에 품고 글을 써 나간다면, 올바른 방향으로 기술 글쓰기를 완성해 나갈 수 있을 거예요.

(기술 글쓰기를 각 단계 별로 다르게 정의하는 이 방식은, 저의 굉장히 주관적인 접근입니다. 기술 글쓰기에 대해 학술적으로 잘 정리된 좋은 자료들도 많아요.

다만 저는 이 방식을 통해, 여러분이 각 단계에서 무엇에 집중해야 하는지를 말씀드리고 싶었어요. 동시에 기술 글쓰기의 복합적이고도 다양한 측면을 보여드리고도 싶었고요.)

기술 글쓰기 4원칙

앞에서 이야기한 두 질문을 조금 더 구체적이고 실천 가능한 기준으로 정리한 것이 바로 기술 글쓰기의 4원칙-정확성, 명확성, 간결성, 일관성-입니다.

이 네 가지 원칙은 기술 글쓰기의 기본이자 핵심이므로, 글을 쓰는 내내 항상 염두에 두어야 해요. 이제 각 원칙이 어떤 의미인지 하나씩 살펴볼게요.

정확성

정확성이란 '기술적 오류 없이, 정확하게 쓰는 것'을 의미해요.

기술 문서의 가장 큰 역할은 정보의 전달이기 때문에, 정보의 정확성은 매우 중요합니다. 아무리 뛰어난 문장으로 작성된 문서라도, 정보 자체가 정확하지 않다면 쓸모없는 문서가 돼요.

내가 이미 아는 내용이라고 해도, ‘정말 맞는 내용인가?’를 끊임없이 의심하고 확인하는 자세가 필요합니다!!

예:❌ 이 API는 모든 브라우저에서 작동합니다.✅ 이 API는 Chrome 136.0, Firefox 137.0 버전에서 테스트되었습니다.

체크리스트

• 사실에 기반한 정보인가?
• 검증된 정보(예제, 코드)인가?
• 최신의 정보인가?
• 출처를 명시하였는가?

명확성

명확성이란 '독자가 이해하기 쉽게 쓰는 것'을 의미해요.

기술 문서가 전달하는 정보는 독자에게는 새로운 정보입니다. 나는 잘 알고 있는 정보지만요. 내가 설명하기 편하게 가 아니라, 독자가 이해하기 쉽게 써야 합니다. 독자는 나와 같은 맥락에 있지 않아요.

이 문서를 쓰고 있는 이유를 잘 생각해 보세요. 단순히 내가 알고 있는 것을 나열하기 위해서가 아니라, 독자에게 내가 알고 있는 것을 전달하기 위해 쓰고 있는 것입니다!

예:❌ 서버가 응답하지 않을 수도 있습니다.✅ 서버가 5초 이내에 응답하지 않으면 타임아웃 오류가 발생합니다.

체크리스트

• 중의적 표현이 없는가?
• 이해하기 어려운 문장이 없는가?
• 문장 간, 문단 간 흐름이 연결되는가?
• 기술 용어가 적절히 사용 또는 정의되었는가?
• 예시나 시각 요소를 적절히 활용하였는가?

간결성

간결성이란 '짧고 간결하게 쓰는 것'을 의미해요. 

긴 문장은 가독성을 떨어뜨리고, 복잡한 문장 구조는 독자의 이해도를 낮춰요. 효과적으로 정보를 전달하기 위해 간결한 문장은 필수입니다.

꼭 필요한 표현만 남기세요. 그리고 완성된 문장을 소리 내어 읽어보세요. 한 번에 읽히지 않고 중간에 끊어 읽어야 한다면, 너무 긴 문장입니다.

예:❌ 이 기능은 사용자가 로그인한 이후에만 사용할 수 있으며, 로그인하지 않은 상태에서는 사용할 수 없습니다.✅ 이 기능은 로그인 후에만 사용할 수 있습니다.

체크리스트

• 불필요한 표현(수식어, 반복 등)이 없는가?
• 문장 길이가 적절한가?
• 효율적인 표시 형식(표, 목록 등)을 사용하였는가?

일관성

일관성이란 '일정한 용어와 형식을 사용하는 것'을 의미해요.

문서 전체에서 용어와 형식이 일관성 있게 사용되면, 독자는 문서의 내용을 더욱더 신뢰합니다. 문서의 가독성이나 독자의 이해도가 올라가는 것은 물론이고요.

쓰는 사람 입장에서도 미리 규칙을 정해두면 편하답니다. 용어집을 정의하여 일정하게 사용하고, 제목이나 기타 요소들의 표시 형식을 정해두고 사용해 보세요. 나올 때마다 고민하지 않아도 됩니다!

예:❌ '사용자', '유저', '클라이언트'가 혼용✅ '사용자'로 통일

체크리스트

• 용어, 표현, 톤이 일관되게 사용되었는가?
• 제목의 형태나 표기 방식이 일관적인가?
• 코드, 인용, 링크 등의 표기 방식이 일관적인가?
• 시각 요소(표, 코드 등)의 스타일이 통일되었는가?

이 원칙들을 지키는 것은 문서 자체의 완성도 뿐 아니라, 독자의 이해도와 신뢰도를 높일 수 있는 비결입니다.

처음부터 완벽하게 지키는 것은 어렵더라도, 쓰는 과정에서, 또 (다음 편에서 다를) 다듬는 과정에서 항상 이 원칙들을 지키려고 노력해 보세요.

읽기 편하고 이해하기 쉬우면서도 정확한 문서! 그런 '잘 쓴' 기술 문서에 한 걸음 다가가게 될 거에요!

K 개발자가 되려면, 기계 번역도 고려하자

K 팝, K 드라마, K 푸드... 한국을 의미하는 K가 다양한 영역에 붙어 그 자체로 브랜드로 여겨지고 있는데요. 우리도 곧 세계로 뻗어나갈(!! 혹시 이미 유명한데 저만 모르나요...) K 개발자 브랜드를 위해 조금 노력을 해 봐요!

내가 쓰는 문서가 AI나 기계 번역을 거쳐, 미국 실리콘 밸리나 인도 벵갈루루¹⁾의 어느 개발자에게 전달될 수도 있는 시대이니까요. 물론 가깝게는 우리가 협업하고 있는 해외 연구소의 개발자나 테스트 담당자들이 읽게 될 수도 있고요.

사실 기계 번역이 잘 되는 문서가 따로 있는 건 아니에요. 위에서 말한 4 원칙-정확성, 명확성, 간결성, 일관성- 을 잘 지키는 것으로 충분합니다.

그렇지만, 그중에서도 특히 더 신경 써야 할 원칙을 꼽자면 명확성과 간결성일 것 같아요.

• 첫 번째로 명확성이 중요한 이유는 바로 '맥락의 필요성' 때문인데요. 앞에서 독자가 나와 같은 맥락에 있지 않다고 말씀드렸었는데, 하물며 기계는 어떻겠어요. 게다가 챗지피티나 구글 번역기는 우리랑 국적(?!)도 다른걸요. 그러니 충분한 맥락 정보 (필요한 경우 문화적 차이도 고려한)를 제공해야 해요. 다른 뜻으로 오해하지 않도록.
• 두 번째로 간결성이 중요한 이유는 길고 복잡한 문장은 기계도 헷갈려하기 때문이에요. 문장이 길어질수록, 여러 다른 뜻으로 해석될 가능성도 커집니다. 한 문장에는 하나의 중요 정보만 담고, 가능한 '주어+서술어' 형태의 간단한 구조를 사용하세요.

오늘은 이 정도로만 하고, 다음에 번외 편으로 '기계 번역 잘되는 문장 쓰기'를 따로 이야기해볼게요. 그때는 예시와 함께 좀 더 구체적인 팁을 드리도록 하겠습니다.

이제 남은 건 고치기, 다시 쓰기, 다듬기

와 이제 가장 길고 지난한 단계를 지나셨어요. 정말 고생하셨습니다! ദ്ദി・ᴗ・)✧

저도 기술 글쓰기 업무를 거의 10년째 하고 있지만, 내 머릿속에 있는 생각과 아이디어를 글로 풀어내는 일이 늘 어려워요.

그렇게 어찌어찌 힘들게 페이지를 채우고 다음 날 다시 읽어보면 싹 다 지워버리고 싶은 적이 한두 번이 아니었답니다.

( ⁍᷄⌢̻⁍᷅ )

하지만 용기를 내고 희망을 가져보아요. '노인과 바다'를 쓴 그 유명한 작가 어니스트 헤밍웨이도 "모든 초고는 쓰레기다"라고 했대요.

비록 한참 부족해 보이는 이 초안도 고치고, 다시 쓰고, 다듬고 하다 보면 썩 괜찮아질지도 몰라요.

그럼 다음 포스팅은 마지막 '4단계: 검토하기'를 가지고 돌아오겠습니다. (마지막이라니 벌써 아쉬우시죠?? 저만 그런 거 아니죠??? ♡ ᐡ◕ ̫ ◕ᐡ ♡) 오늘도 읽어주셔서 감사합니다!

1) 벵갈루루는 인도 카르나타카의 주도이자 인도의 실리콘밸리로 불리는 도시입니다. (https://en.wikipedia.org/wiki/Bengaluru)