사용자 문서: 문제의 원인과 해결 방법

소프트웨어 문서는 단지 일련의 기사일 뿐입니다. 하지만 심지어 그들은 당신을 미치게 만들 수도 있습니다. 첫째, 필요한 지침을 찾는 데 오랜 시간을 보냅니다. 그러면 모호한 텍스트를 이해하게 됩니다. 쓰여진 대로 했지만 문제가 해결되지 않았습니다. 다른 기사를 찾다가 긴장됩니다... 한 시간 후에 모든 것을 포기하고 떠납니다. 이것이 나쁜 문서가 작동하는 방식입니다. 원인과 해결 방법 - 아래 내용을 읽어보세요.

이전 문서에는 많은 단점이 있었습니다. 위에서 설명한 시나리오가 고객에게 영향을 미치지 않도록 우리는 거의 XNUMX년 동안 이를 재작업해 왔습니다. 바라보다, 그랬던 것처럼 и 어떻게이 일이 일어 났어요.

문제 1: 불분명하고, 형편없는 기사

문서를 이해하는 것이 불가능하다면, 그 문서의 요점은 무엇입니까? 하지만 일부러 이해하기 어려운 글을 쓰는 사람은 없습니다. 저자가 독자와 목적을 생각하지 않고 물을 붓고 텍스트의 오류를 확인하지 않을 때 발생합니다.

• 관객. 기사를 쓰기 전에 독자의 준비 수준을 생각해 볼 필요가 있습니다. 초보자를 위한 기사에서는 기본 단계를 건너뛰거나 기술 용어를 설명 없이 남겨서는 안 되지만, 전문가에게만 필요한 희귀 기능에 대한 기사에서는 PHP라는 단어의 의미를 설명해야 하는 것이 논리적입니다.
• 골. 미리 생각해 볼 것이 하나 더 있습니다. 저자는 명확한 목표를 설정하고, 기사의 유용한 효과를 판단하고, 독자가 기사를 읽은 후 무엇을 할지 결정해야 합니다. 이것이 안되면 설명을 위한 설명으로 끝나게 됩니다.
• 물과 벌레. 불필요한 정보가 많고 관료주의, 오류, 오타가 인식을 방해합니다. 독자가 문법 나치가 아니더라도 텍스트의 부주의로 인해 독자가 흥미를 잃을 수 있습니다.

위의 팁을 고려하면 기사가 더 명확해질 것입니다. 더 나은 결과를 얻으려면 기술 문서 작업 시 50가지 질문.

문제 2. 기사가 모든 질문에 답하지 않습니다.

문서가 개발 과정을 따라가지 못하고, 실제 질문에 대답하지 않고, 문서의 오류가 수년 동안 수정되지 않으면 좋지 않습니다. 이는 작성자의 문제가 아니라 회사 내 프로세스 구성의 문제입니다.

문서가 개발 속도를 따라가지 못함

이 기능은 이미 출시되어 마케팅 계획에 포함되어 있지만 새로운 기사나 번역이 아직 문서에 없는 것으로 나타났습니다. 이 때문에 출시를 연기해야 ​​하기도 했습니다. 원하는 만큼 모든 사람에게 기술 작성자에게 작업을 제 시간에 넘겨달라고 요청할 수 있지만 작동하지 않습니다. 프로세스가 자동화되지 않으면 상황은 반복됩니다.

YouTrack이 변경되었습니다. 새로운 기능에 대한 기사를 작성하는 임무는 기능 테스트가 시작되는 동시에 기술 작성자의 몫입니다. 그런 다음 마케팅에서는 프로모션을 준비하기 위해 이에 대해 학습합니다. 알림은 Mattermost 기업 메신저로도 전달되므로 개발자의 소식을 놓치는 것은 불가능합니다.

문서에 사용자 요청이 반영되지 않음

우리는 이런 식으로 작업하는 데 익숙합니다. 기능이 나왔고 그것에 대해 이야기했습니다. 켜고 끄는 방법과 미세 조정하는 방법을 설명했습니다. 하지만 클라이언트가 우리가 예상하지 못한 방식으로 우리 소프트웨어를 사용한다면 어떻게 될까요? 아니면 우리가 생각하지 못한 오류가 있는 걸까요?

문서가 최대한 완벽하도록 하려면 지원 요청, 주제별 포럼의 질문, 검색 엔진의 쿼리를 분석하는 것이 좋습니다. 가장 인기 있는 주제는 기술 작성자에게 이전되어 기존 기사를 보완하거나 새 기사를 작성할 수 있습니다.

문서가 개선되지 않습니다

당장 완벽하게 하기는 어렵고, 실수도 있을 것입니다. 고객의 피드백을 기대할 수는 있지만 오타, 부정확성, 이해할 수 없거나 찾을 수 없는 기사를 모두 보고할 가능성은 거의 없습니다. 클라이언트 외에도 직원들도 문서를 읽었는데, 이는 동일한 오류를 보게 된다는 의미입니다. 이것은 사용할 수 있습니다! 문제를 쉽게 보고할 수 있는 조건을 만들기만 하면 됩니다.

내부 포털에는 직원들이 문서에 대한 의견, 제안, 아이디어를 남기는 그룹이 있습니다. 지원을 받으려면 기사가 필요하지만 기사가 존재하지 않나요? 테스터가 부정확성을 발견했습니까? 파트너가 개발 관리자에게 오류에 대해 불만을 제기했습니까? 이 그룹의 모든 것! 기술 작성자는 일부 사항을 즉시 수정하고, 일부 사항을 YouTrack으로 전송하고, 다른 사람들에게 생각할 시간을 줍니다. 주제가 사그라드는 것을 방지하기 위해 때때로 그룹의 존재와 피드백의 중요성을 상기시켜 드립니다.

문제 3. 올바른 기사를 찾는 데 시간이 오래 걸립니다.

찾을 수 없는 기사는 찾을 수 없는 기사보다 나을 것이 없습니다. 좋은 문서의 모토는 "검색하기 쉽고 찾기 쉽다"입니다. 이것을 달성하는 방법은 무엇입니까?

구조를 구성하고 주제 선택 원칙을 결정합니다.. 독자가 “이 기사를 어디서 찾을 수 있지?”라고 생각하지 않도록 구조는 최대한 투명해야 합니다. 요약하면 인터페이스와 작업의 두 가지 접근 방식이 있습니다.

1. 인터페이스에서. 콘텐츠는 패널 섹션을 복제합니다. 이는 이전 ISPsystem 문서의 경우였습니다.
2. 작업에서. 기사 제목과 섹션은 사용자의 작업을 반영합니다. 제목에는 거의 항상 "방법" 질문에 대한 동사와 답변이 포함되어 있습니다. 이제 우리는 이 형식으로 전환하고 있습니다.

어떤 접근 방식을 선택하든 주제가 사용자가 찾고 있는 것과 관련이 있고 사용자의 질문을 구체적으로 해결하는 방식으로 다루어져야 합니다.

중앙 집중식 검색 설정. 이상적인 세상에서는 철자가 틀리거나 언어에 실수가 있는 경우에도 검색이 작동해야 합니다. 지금까지 Confluence에서 검색한 내용으로는 만족할 수 없습니다. 제품이 많고 문서가 일반적인 경우 사용자가 있는 페이지에 맞게 검색을 조정하세요. 우리의 경우 메인 페이지의 검색은 모든 제품에 대해 작동하며 이미 특정 섹션에 있는 경우 해당 섹션에 있는 기사에 대해서만 검색됩니다.

콘텐츠 및 탐색경로 추가. 각 페이지에 메뉴와 이동 경로(모든 레벨로 돌아갈 수 있는 기능이 있는 현재 페이지에 대한 사용자 경로)가 있으면 좋습니다. 이전 ISPsystem 문서에서는 콘텐츠를 보려면 해당 문서를 종료해야 했습니다. 불편해서 새로 고쳤습니다.

제품에 링크 배치. 사람들이 같은 질문으로 계속해서 지원을 한다면 인터페이스에 솔루션과 함께 힌트를 추가하는 것이 합리적입니다. 사용자에게 문제가 발생하는 시점에 대한 데이터나 통찰력이 있는 경우 메일링 리스트를 통해 알릴 수도 있습니다. 그들에게 관심을 보여주고 지원의 부담을 덜어주세요.

팝업 창 오른쪽에는 ISPmanager의 도메인 관리 섹션에서 DNSSEC 설정에 대한 기사 링크가 있습니다.

문서 내에서 상호 참조 설정. 서로 관련된 기사는 "링크"되어야 합니다. 기사가 순차적인 경우 각 텍스트 끝에 앞으로 및 뒤로 화살표를 추가하십시오.

아마도 사람은 먼저 자신의 질문에 대한 답변을 귀하가 아닌 검색 엔진에서 찾을 것입니다. 기술적인 이유로 문서에 대한 링크가 없다면 안타까운 일입니다. 그러니 검색엔진 최적화에 신경쓰세요.

문제 4. 오래된 레이아웃이 인식을 방해함

잘못된 텍스트 외에도 문서는 의도적으로 손상될 수 있습니다. 사람들은 잘 쓰여진 자료를 읽는 데 익숙합니다. 블로그, 소셜 네트워크, 미디어 등 모든 콘텐츠는 보기에도 좋고 읽기 쉽고 보기에도 좋습니다. 그러므로 아래 스크린샷처럼 텍스트를 보는 사람의 고통을 쉽게 이해할 수 있습니다.

이 기사에는 스크린샷과 하이라이트가 너무 많아서 도움이 되지 않고 인식에만 방해가 됩니다(사진을 클릭할 수 있음).

다양한 효과가 포함된 문서를 길게 읽어서는 안 되지만 기본 규칙을 고려해야 합니다.

공들여 나열한 것. 본문 텍스트 너비, 글꼴, 크기, 제목 및 패딩을 결정합니다. 디자이너를 고용하고 작업을 수락하거나 직접 작업하려면 Artyom Gorbunov의 저서 "Typography and Layout"을 읽어보세요. 레이아웃에 대한 하나의 뷰만 제공하지만 그것만으로도 충분합니다.

배당. 본문에서 강조해야 할 것이 무엇인지 결정하십시오. 일반적으로 이는 인터페이스, 버튼, 코드 삽입, 구성 파일, "참고" 블록의 경로입니다. 이러한 요소의 할당이 무엇인지 결정하고 이를 규정에 기록합니다. 방전이 적을수록 좋습니다. 너무 많으면 텍스트가 시끄러워집니다. 따옴표라도 너무 자주 사용하면 소음이 발생합니다.

스크린샷. 어떤 경우에 스크린샷이 필요한지 팀과 합의하세요. 모든 단계를 설명할 필요는 없습니다. 스크린샷을 포함한 다수의 스크린샷. 버튼을 분리하면 인식이 방해되고 레이아웃이 망가집니다. 스크린샷의 하이라이트와 서명의 크기와 형식을 결정하고 이를 규정에 기록합니다. 삽화는 항상 쓰여진 내용과 일치해야 하며 관련성이 있어야 한다는 점을 기억하십시오. 다시 말하지만, 제품이 정기적으로 업데이트되면 모든 사람을 추적하기가 어려울 것입니다.

텍스트 길이. 지나치게 긴 기사는 피하세요. 여러 부분으로 나누고 이것이 불가능할 경우 기사 시작 부분에 앵커 링크가 포함된 콘텐츠를 추가하세요. 기사를 시각적으로 더 짧게 만드는 간단한 방법은 스포일러 아래에 좁은 범위의 독자에게 필요한 기술적 세부 사항을 숨기는 것입니다.

형식. 기사에 텍스트, 비디오, 이미지 등 여러 형식을 결합하세요. 이렇게 하면 인식이 향상됩니다.

아름다운 레이아웃으로 문제를 은폐하려고 하지 마세요. 솔직히 우리는 "래퍼"가 오래된 문서를 저장하기를 바랐지만 제대로 작동하지 않았습니다. 텍스트에는 너무 많은 시각적 잡음과 불필요한 세부 사항이 포함되어 있어 규정과 새로운 디자인이 무력했습니다.

위의 내용 중 대부분은 문서화에 사용하는 플랫폼에 따라 결정됩니다. 예를 들어 Confluence가 있습니다. 나도 그와 땜질해야 했어요. 관심이 있으시면 웹 개발자의 이야기를 읽어보세요. 공개 지식 기반을 위한 합류: 디자인 변경 및 언어별 분리 설정.

개선을 시작하는 곳과 생존 방법

문서가 ISPsystem만큼 방대하고 어디서부터 시작해야 할지 모른다면 가장 큰 문제부터 시작하십시오. 고객은 문서를 이해하지 못합니다. 텍스트를 개선하고, 규정을 만들고, 작가를 교육합니다. 문서가 오래되었습니다. 내부 프로세스를 관리하세요. 가장 인기 있는 제품에 대한 가장 인기 있는 기사부터 시작하세요. 지원을 요청하고, 사이트 분석 및 검색 엔진 쿼리를 살펴보세요.

지금 당장 말해 봅시다. 쉽지 않을 것입니다. 그리고 빨리 작동할 것 같지도 않습니다. 막 시작해서 바로 옳은 일을 하는 것이 아니라면 말이죠. 우리가 확실히 알고 있는 한 가지는 시간이 지남에 따라 좋아질 것이라는 것입니다. 그러나 그 과정은 결코 끝나지 않을 것입니다 :-).

출처 : habr.com