효과적인 기술 문서 작성 전략

저는 1999년 이스라엘 크파르 사바(Kfar Saba)에 있는 Altec Lansing의 R&D 지점에서 QA를 할 때부터 다양한 종류의 기술 문서 작성을 해왔습니다. 그 당시 우리는 Windows ME 및 2000에서 작동하는 USB 오디오 장치와 같은 혁신적인 오디오 관련 장치를 출시했습니다. 버그가 많았고 설정이 오늘날처럼 간단하지 않았습니다.

우리는 문서가 필요했습니다.

우리는 사용자가 뛰어넘어야 하는 몇 가지 난관이 있었고, 그것이 무엇인지, 극단적인 경우는 무엇인지, 모든 것을 진단하고 수정하는 방법을 문서화할 방법이 필요했습니다. 멋지게 패키징되고, 깔끔한 형식이 지정되어야 하며, 도우미 애플리케이션을 설치한 사용자가 액세스할 수 있어야 했습니다. Windows에서 표준 도움말 응용 프로그램을 만드는 데 사용되는 Robohelp 응용 프로그램을 찾아 설치에 도움말 파일을 추가했습니다.

QA 프로세스 중에 우리는 문제를 식별하고, 중요하다고 생각하는 내용을 문서화하고, 이를 장치와 함께 번들로 제공되는 도움말 파일로 구성했습니다. 당시 저는 19살이었고 이런 일에 대한 경험이 전혀 없었고 그것은 엄청나게 순진한 과정이었습니다. 그럼에도 불구하고 이는 사용자를 위해 옳은 일이라고 느꼈고 관리자는 나에게 그렇게 하지 말라고 명시적으로 지시하지 않았습니다.

24년이 지났고 그 이후로 저는 여러 프로젝트에 대한 문서 작업을 해왔습니다. 규모가 커졌고 이러한 유형의 프로젝트를 보는 방식이 크게 바뀌었습니다.

나는 좋은 문서를 만드는 방법에 대해 몇 가지 생각을 갖고 있으며 관심이 있으시면 이를 공유하고 싶습니다.

핵심 문서화 개념

나는 문서화 제품의 성공에 중요하다고 생각되는 보다 구체적인 규칙 세트부터 시작하고 싶습니다.

• 문서에서는 큰 아이디어를 설명하기 위해 짧은 단어를 사용해야 합니다 . 따라서 더 간단한 용어로 말할 수 있는 내용을 설명하기 위해 화려한 단어나 복잡한 문장을 사용하지 마세요. 도중에 사용자를 잃게 되며 이는 작가의 자존심을 상하게 할 가치가 없습니다.

• 문서는 가능한 한 이야기를 전달해야 합니다 . 이야기를 전달하는 개인적이고 관련성 높은 작업 집합은 추상적인 지침 집합보다 사용자에게 더 매력적이고 기억에 남을 것이기 때문입니다.

• 문서는 검색 가능해야 합니다 . 왜냐하면 진지하게 말하면 이는 생각할 필요도 없는 일이기 때문입니다. 문서에서 내용을 찾기가 쉽지 않으면 사용자는 필요한 것을 찾지 못할 것입니다.

• 문서는 거의 항상 더 큰 전략의 일부 이며, 소프트웨어 제품의 경우 특히 그렇습니다. 이는 개발자 옹호라는 더 큰 주제를 다루지만 간단히 말해서 문서는 비디오 튜토리얼, 실제 사용 예제 및 실시간 기술 지원을 통해 지원되어야 합니다.

• Docs를 테스트해야 합니다 . 모든 것이 올바른지 확신할 수 있지만 다른 제품과 마찬가지로 실제 사용자가 없으면 확신할 수 없기 때문입니다. 테스트하고 다시 테스트해 보세요.

  
  

전체적인 문서는 잘 설계된 제품입니다.

새로운 프로그래밍 언어를 배우면 해당 언어의 개념과 아이디어가 문제 해결 요령으로 흘러 들어갑니다. 그것은 당신을 더 나은 소프트웨어 개발자로 만들고 결국 당신이 더 잘 알고 능력이 있기 때문에 더 나은 소프트웨어를 만드는 것입니다.

내 경력은 복잡했으며 소프트웨어 제품 디자인, 소프트웨어 개발, 기술 지원 및 개발자 옹호 활동이 많이 포함되었습니다. 각 분야는 내가 다른 사람을 생각하고 접근하는 방식에 영향을 미쳤습니다.

제가 기술 문서 작성 프로젝트에 접근할 때는 사용자에게 필요한 것이 무엇인지에 대한 광범위한 관점을 가지고 접근합니다. 나는 그것이 문서를 전체적으로 생각하는 올바른 방법이라고 생각합니다. 문서는 잘 정의된 것이 아니며 좋은 문서를 만들려면 유연성이 있어야 합니다.

나에게 이는 가능한 한 많은 각도에서 사용자를 생각해야 함을 의미합니다. 어떤 것도 당연하게 여길 수 없으며, 그렇지 않으면 일부 사용자 그룹이 브랜드, 제품 또는 비즈니스에 부정적인 영향을 미치고 회복하기 어려운 방식으로 실망하게 될 것입니다.

귀하의 문서는 사용자에게 성패를 좌우하는 경험이 되는 경우가 많습니다.

일을 잘 수행하면 사용자는 제품을 성공적으로 사용하고 브랜드의 챔피언이 될 것입니다. 그렇지 않으면 귀하의 문서가 그들의 마음 속에 나쁜 맛을 남겼기 때문에 그들은 귀하의 제품을 다시는 사용하지 않을 것입니다. 그들은 또한 다른 사람들에게도 알릴 것입니다. 좋은 마케팅은 여기에서 시작되므로 이를 명심하세요.

좋은 문서 만들기

좋은 문서를 만든다는 것은 다른 제품 프로세스와 마찬가지로 문서 작성에 접근해야 한다는 의미입니다.

다음을 수행해야 합니다.

• 문서를 만드는 이유를 알아보세요
• 타겟 고객이 누구인지 파악하세요
• 그들의 문제점이 무엇인지 파악하십시오.
• 시간이 지남에 따라 문서를 개선하세요

각각에 대해 자세히 살펴보겠습니다.

문서의 이유를 아는 것은 표면적으로 매우 간단한 질문과 답변인 경우가 많습니다. 문서를 작성하는 이유는 그렇지 않으면 사용자가 어려움을 겪고 제품을 사용하지 못하게 되기 때문입니다. 더 깊은 수준에서는 사용 사례에 대한 구체적인 답변이 있습니다. 개발자 도구가 있나요? 그것은 하나의 답변 세트입니다. 소매점 디자인 도구가 있나요? 회계 SaaS 제품이 있습니까? 자동 커피 메이커가 있나요? 이것들은 모두 별도의 답변 세트입니다.

문서의 형식은 문서를 사용할 사람에 따라 설명됩니다. 온라인인가요? 앱과 함께 번들로 제공되나요? 인쇄되어 있나요? 모든 사용자 기반에는 다른 것이 필요하며 처음부터 그들이 누구인지 명확하게 밝혀야 합니다.

귀하의 임무는 각 사용자에게 어려운 점을 파악하고 특정 문제를 해결하는 유익한 콘텐츠를 통해 사용자를 안내하는 문서를 만드는 것입니다.

가장 중요한 것은 처음부터 제대로 되지 않을 수도 있다는 점을 알아야 한다는 것입니다. 이는 시간이 지남에 따라 제품이 성장하고 변화함에 따라 문서를 유지 관리하고 업데이트해야 함을 의미합니다. 도움을 주고자 하는 사용자와 쉽게 소통할 수 있는 프레임워크 내에서 이 작업이 수행되기를 바랍니다. 사용자와 대화하고, 그들의 요구 사항에 귀를 기울이고, 문서를 사용하여 제품 사용 경험을 더 좋게 만들어야 합니다.

귀하의 문서는 성공의 필수적인 부분입니다

문서가 얼마나 중요한지 간단히 강조하여 요약하겠습니다. 이러한 기능이 없으면 사용자는 스스로 책임을 져야 하며 스스로 책임을 져야 합니다.

이는 항상 성공 사례 감소, 생태계 내 제품에 대한 부정적인 시각, 개발자나 사용자의 불만 증가, 브랜드나 회사에 부정적인 영향을 의미합니다.

문서도구는 그 자체로 중요한 하위 제품이자 투자이며 더 넓은 제품 전략의 일부가 되어야 합니다.