좋은 문서 작성에 대한 입문서

이 게시물은 게스트 작성자 Jeff Matson이 제공했습니다. Jeff는 GravityForms의 문서 책임자입니다. 그는 Heartbeat Control WordPress 플러그인의 창시자이며 90년대의 팬입니다.

종종 문서화는 개발 프로세스에서 가장 과소평가된 부분입니다. WordPress 커뮤니티에서 록스타를 볼 때 일반적으로 개발자, 디자이너 및 마케터를 봅니다. 모든 것이 순조롭게 진행되도록 피, 땀, 눈물을 흘린 문서 작성자에 대해서는 알려진 바가 거의 없습니다.

이 게시물은 개발자가 생각한 것과 존재하는 코드 뒤에 숨겨진 진정한 의미를 해독하기 위해 끝없는 코드 줄을 하루 종일 응시하는 사람들에 관한 것입니다.

좋은 문서는 말 그 이상입니다

훌륭한 문서 작성자는 사용 설명서 그 이상을 제공할 뿐만 아니라 경험을 제공합니다. 나는 훌륭한 문서작가와 코칭 초보자를 알고 있는데, 그들 사이의 가장 큰 차이점은 그것을 읽는 사람들의 두뇌를 이해한다는 것입니다. 소설과 마찬가지로 문서에는 독자의 관심을 유지하고 그들이 깨닫는 것보다 더 많은 정보를 섭취하게 하는 흐름이 있습니다.

품질 문서는 읽을 가능성이 가장 높은 사용자를 대상으로 합니다. 또한 읽기 어려운 사람들을 위해 참조 지점을 제공합니다. 예를 들어, 특정 후크를 문서화하는 경우 일반적으로 개발자가 이를 읽을 것이라고 가정하지만 개발 경험이 거의 없는 사람들은 어떻습니까?

좋은 문서 작성자는 올바른 방향으로 더 많은 노력을 기울여야 하는 사람들을 위해 참조 지점을 제공할 것입니다.

문서는 생각보다 큰 영향을 미칩니다

대부분은 문서를 무시하고 더 이상 견딜 수 없을 때까지 끝없는 심연으로 밀어 넣습니다. 나는 어떤 경우에는 같은 죄를 범한다. 그 사람들이 깨닫지 못하는 것은 플러그인이나 테마가 문서화되지 않은 상태로 남겨질 때마다 사용자 경험이 악화된다는 것입니다.

가장 일반적인 지원 티켓을 살펴보겠습니다. 해당 문제를 더 잘 문서화하면 해당 티켓이 완전히 사라질 것입니까? 아마 아닐 것입니다. 문제와 관련된 티켓을 덜 받고 귀하 또는 귀하의 지원 상담원의 생산성을 높이시겠습니까? 보증합니다. 나는 우리 모두가 더 적은 수의 지원 티켓을 사용할 수 있다고 생각합니다.

앞서 언급했듯이 문서화는 사용자 경험에 극적인 영향을 미칩니다. 사용자가 정보를 쉽고 효율적으로 찾을 수 있다면 사용자는 물론 자신의 시간도 절약할 수 있습니다. 평균 세계 평균 수명은 66.57세이며 사용자는 형편없이 작성된 문서를 만지작거리기보다는 삶을 위해 다른 일을 하고 싶어합니다.

고객이 문서화에 상당한 시간과 노력을 들인 것을 보면 의식적이든 아니든 감사할 것입니다. 좋은 문서는 초기 판매 이후에 당신이 그것들에 관심을 가지고 있음을 보여줍니다.

힘들게 번 돈을 쓰고 나서 곧 구매를 후회한 적이 있습니까? 우리 모두가 가지고 있다고 생각합니다. 적절한 문서화를 통해 고객에게 이러한 감정을 전달하는 것을 방지할 수 있습니다.

어떻게 더 나은 문서를 작성할 수 있습니까?

첫 번째 단계는 그것을 피하는 것을 멈추는 것입니다. 문서 작성에 능숙해지면 생각보다 즐거운 경험이 될 것입니다. 사실, 그것은 제2의 천성이 될 것입니다. 세상의 모든 것과 마찬가지로 연습이 완벽을 만듭니다.

문서를 다음 단계로 끌어올리기로 결정할 때 취하려는 첫 번째 단계 중 하나는 문제점을 파악하는 것입니다. 무엇에 대해 연락을 받고 있습니까? 맹목적으로 어떤 것에 대해 쓰기 시작한다면, 당신이 쓰고 있는 것이 원하는 만큼 큰 영향을 미치지 않는다는 것을 알게 될 것입니다.

내가 발견한 최고의 기술 중 하나는 문서화된 티켓 수와 그렇지 않은 티켓 수를 추적하고 범주에 속하지 않는 티켓을 나누는 것입니다. 이렇게 하면 문제점을 더 잘 목표로 삼고 도움이 되지 않을 수 있는 부분을 수정해야 합니다.

어떤 문서를 작성해야 하는지 결정했으면 대상 독자를 결정하고 개발자, 사용자 및 고급 사용자로 분류해야 합니다. 이것은 특정 청중을 수용하는 데 도움이 됩니다. 이러한 사용자를 대상으로 하는 방법은 잠시 후에 살펴보겠습니다.

다음으로 문서를 분해하려고 합니다. 개발자의 경우 원시 정보(허용되는 인수, 반환 값 등), 특정 예제 및 사용 사례로 분류하고 싶을 것입니다. 사용자에게 가장 좋은 방법은 연습입니다. 아무리 사소해 보일지라도 그들이 취해야 할 모든 단계는 매우 중요합니다.

모든 단계에서 그들에게 그것을 철자하십시오. 고급 사용자를 위한 문서화는 사용자 시나리오와 매우 유사하지만 더 구조화되고 스캔 가능합니다. 명확하게 하되 이전 단계를 먼저 읽지 않고도 원하는 곳으로 쉽게 이동할 수 있도록 하십시오.

더 나은 문서 작성 기술

문서 작성 기술과 관련하여 청중을 가장 잘 타겟팅하는 방식으로 작성하되 그들이 이해할 수 있는 간단한 언어를 사용하십시오. 가장 좋은 이유 중 하나는 번역 때문입니다. Google 번역이 훌륭한 일을 하지만 대학원 논문에 포함된 것보다 5학년 학생의 간단한 어휘를 번역하는 것이 훨씬 쉽습니다.

콘텐츠 내에서 관련 콘텐츠에 연결하는 것을 두려워하지 마십시오. 이렇게 하면 여러 문서를 통해 자신을 반복하는 것을 피할 수 있을 뿐만 아니라 독자가 특정 주제에 대한 추가 정보가 필요한 경우 역추적할 수 있습니다. 결국, 주요 목표는 사용자를 행복하게 하고 시간을 절약하는 것입니다.

게시 버튼을 누른 후에도 문서화 프로세스가 중지되지 않습니다. 돌아가서 필요에 따라 모든 문서를 수정하십시오. 문서가 게시된 직후에 돌아가서 추적한 지원 티켓이 거부되었는지, 특정 문서에 대한 트래픽이 증가했는지 확인하십시오. 일반적으로 기사에 더 많은 트래픽이 발생하면 도움이 됩니다. 더 많은 트래픽이 발생하지만 동일한 수의 지원 티켓이 발생하는 경우 해당 문서를 살펴보고 그 이유를 확인할 수 있습니다.

우리가 배운 것

먼저, 여기까지 온 후 우리 대부분이 당연하게 여기는 문서를 작성하는 참호에 대해 더 잘 이해하기를 바랍니다. 이것은 생계를 위해 문서를 작성하는 많은 사람들이 진정으로 즐기고 많은 시간을 투자하는 예술 형식입니다.

또한 이 문서에서 벗어나 기존 문서와 문서 개선 방법에 대해 더 많이 생각하기를 바랍니다. 적절한 문서화는 매우 보람이 있을 수 있으며 실제로 한 번 작성하면 실제로 매우 재미있을 수 있습니다.

일찍 문서화하고 자주 문서화하십시오. 훌륭한 제품은 훌륭한 코드 그 이상이며 아름답게 문서화되어 있습니다.