WordPress 전문가를 위한 제품 문서

게시 됨: 2017-07-28

제품 문서 는 일반적으로 중요하지 않은 것으로 간주되어 모서리를 잘라낼 수 있습니다. 고객에게 가치를 제공할 수 있는 것 또는 수익 및 마케팅과 같은 주요 비즈니스 영역에 영향을 미칠 수 있는 것으로 간주되지 않습니다. 물론 WordPress 전문가는 Atlassian이나 Cisco와 같은 방식으로 문서를 작성할 필요가 없습니다. 일반적으로 사람들은 "문서"를 생각할 때 아무도 읽지 않는 매우 큰 선반에 알파벳순으로 색인된 두꺼운 인쇄된 사용 설명서 이미지를 떠올리게 됩니다.

하지만 다음과 같이 변경되었습니다.

Agile 및 DevOps의 출현으로 소프트웨어 배송이 더 빨라지고 개발 주기도 더 역동적이 되었습니다. 결과적으로 문서는 종이에 영원히 쓰여지는 것이 아니라 최신 릴리스의 현재 상태를 반영합니다. 문서는 개발 주기에 통합되며 소프트웨어만큼 자주 업데이트됩니다.

WordPress 전문가가 제품 문서에 관심을 가져야 하는 이유는 무엇입니까?

유용한 최신 문서는 사용자의 삶을 더 쉽게 만들어 줄 뿐만 아니라 다른 어떤 것과도 비교할 수 없는 마케팅 자산이 되는 수준의 세련미를 추가합니다. 반대로 잘못된 문서는 부정적인 영향을 미칩니다. 당신은 아마 이것을 스스로 경험했을 것입니다. 당신은 문서에서 해결 방법을 찾기 위해 열심히 노력하다가 결국 좌절하고 (아마도 화가 났을) 문제가 있었습니다. 당신이 제품에 대해 지불하는 경우에만 악화됩니다.

WordPress 대행사에서 작업하는 경우 초기 디자인에서 자산에 이르기까지 프로젝트의 모든 영역에 걸쳐 문서를 제공하면 다음을 보여주는 전문성 수준이 추가됩니다.

당신은 세부 사항에주의를 기울입니다.
당신은 추가 마일을 갈만큼 고객에 대해 관심을 가지고 있습니다.
귀하는 설계 및 기술 프로젝트 결정에 대해 투명하고 확신을 갖고 있습니다.

MindTouch Deki의 마케팅 부사장 Mike Puterbaugh는 제품 문서가 마케팅 자산인 5가지 이유를 설명하는 Mashable 기사를 작성했습니다. 그는 다음과 같이 결론지었습니다.

그것은 섹시한 사업은 아니지만 동료의 존경을 받고 보다 효과적인 회사 관리 및 보다 협력적인 팀을 얻을 수 있습니다. 이번 분기나 올해가 아니라 경쟁 우위와 장기적 성장에 영향을 미치기 때문입니다.

이제 충분한 동기 부여가 설정되었으므로 다음을 수행합니다.

WordPress와 관련된 다양한 유형의 제품 문서를 살펴보세요.
각 문서 유형의 요구 사항에 대해 논의하고 실행 가능한 조언을 제공합니다.
제품 문서를 계획하고 공동 작업하는 방법에 대한 몇 가지 초기 지침을 제공합니다. 특히 WordPress 대행사에서 일하는 경우.

WordPress 제품 문서 유형

WordPress 제품은 플러그인과 테마에 관한 것만이 아닙니다. 이 섹션에서는 온라인 도움말, REST API 및 마이크로컨텐츠(microcontent)라는 흥미로운 것에 대해서도 논의할 것입니다.

워드프레스 플러그인

WordPress 플러그인 문서는 사용자와 개발자라는 두 가지 군중을 수용해야 합니다. 사용된 작문 스타일과 마찬가지로 각각의 문서화 요구 사항이 다릅니다.

사용자

사용자의 문서화 요구 사항은 대부분 문제 해결 및 구성과 관련되어 있습니다. 여기에 사용자가 플러그인을 사용해 볼 수 있도록 매력적인 방식으로 플러그인을 제시해야 합니다. 모든 플러그인에는 WordPress 플러그인 시장에 자체 페이지가 있습니다. 다음 사항을 염두에 두십시오.

다운로드 및 사용을 권장하는 설득력 있고 유용한 설명을 작성하십시오.
설명과 함께 대시보드 플러그인 구성 페이지에서 주석이 달린 스크린샷을 추가합니다.
유용하고 진부하지 않은 질문을 FAQ에 넣으십시오.
업데이트되고 잘 작성된 변경 로그가 있습니다. 거기에 애매하거나 간결한 메모를 추가하지 마십시오.

사용자가 문서를 사용할 때 솔루션을 찾기 위해 서두르고 불안할 수 있음을 기억해야 합니다. 명확하고 간단하며 간결하게 작성하십시오. 그들을 지금보다 더 어렵게 만들지 마십시오.

개발자

모범 소프트웨어 사례 및 공식 PHP 코딩 표준을 따르는 것 외에도 다음 영역에 주의를 기울여야 합니다.

플러그인 후크

이들은 WordPress의 동작을 수정하는 작업을 수행합니다. 아마도 WordPress 플러그인이 이를 사용합니다. 플러그인 후크는 코드의 중요한 부분이므로 사용 방법과 관련된 WordPress 기능을 문서화해야 합니다.

템플릿 태그

템플릿 태그는 WordPress 플러그인이 기능을 향상시키는 또 다른 방법입니다. 작성한 템플릿 태그 기능을 문서화하십시오. 다른 사용자나 개발자가 WordPress 사이트에서 태그를 사용하는 방법에 대한 예를 포함합니다.

옵션

옵션은 WordPress 데이터베이스에 특정 정보를 저장하는 방법입니다. 이것은 add_option 및 get_options 함수를 통해 수행됩니다. 이 경우 이러한 함수에 전달하는 매개변수를 문서화하십시오.

데이터 베이스

플러그인은 데이터베이스에서 다양한 항목을 자주 읽고 씁니다. 이는 기본적인 작업이므로 문서화하면 다른 개발자가 플러그인 작동 방식을 이해하는 데 큰 도움이 됩니다.

워드프레스 테마

테마에 대한 문서를 작성할 수 있는 두 가지 영역이 있습니다. 첫 번째는 소스 파일입니다. 주석 처리된 CSS 파일은 없는 것보다 이해하기 쉽고 읽기 쉽습니다. css_doc과 같은 도구를 사용하면 도움이 됩니다. 이것은 JavaDoc 스타일의 문서를 생성하고 게시할 수 있습니다.

다른 영역은 스타일 가이드입니다. 이 문서는 요소가 어떻게 보여야 하고 어떤 경우에 사용해야 하는지 설명합니다. 일관성을 유지하고 공동 작업을 더 쉽게 만듭니다. Hubspot의 20가지 멋진 브랜드 스타일 가이드 사례 기사는 훌륭한 사례가 많이 포함되어 있으므로 읽을 수 있습니다.

다시 말하지만 공식 WordPress CSS 코딩 표준을 참조하는 것을 잊지 마십시오.

디자인 요소를 이렇게 자세하게 문서화하면 WordPress 대행사인 경우 신입 직원의 온보딩에도 도움이 됩니다. 스타일 가이드는 신규 및 과거 클라이언트 작업에 대한 자습서 또는 참조 자료로 사용할 수 있습니다.

온라인 도움말

온라인 도움말은 특정 사용자 문제를 해결하는 것을 목표로 하기 때문에 일반적인 작업 및 문제 목록으로 시작하는 것이 좋습니다. 처음에는 목록이 완전하지는 않지만 시간을 내어 가능한 한 많은 구체적인 항목을 생성하십시오. 아이디어는 이러한 작업과 문제 각각에 대한 온라인 도움말 파일을 작성하고 관련 정보에 하이퍼링크하는 것입니다. 사용자 여정을 생성하여 사용자가 애플리케이션 내에서 선택하고 수행할 수 있는 다양한 경로를 매핑할 수 있습니다. 지원 이메일을 자세히 살펴보고 일반적인 질문과 문제 영역을 확인하는 것은 지식 기반을 최신 상태로 유용하게 유지하는 좋은 방법입니다.

Spring into Technical Writing의 저자 Barry J. Rosenberg는 좋은 도움말 파일을 작성하기 위해 다음과 같은 조언을 제공합니다.

각 도움말 파일을 가능한 한 간략하게 유지하십시오. 글머리 기호 목록보다 번호가 매겨진 목록을 선호합니다. 빗나가지 말고, 각주하지도 말고, 원하지도 마십시오. 각 도움말 파일을 하나의 개별 작업에 집중하십시오.

마이크로컨텐츠

마이크로컨텐츠에는 두 가지 정의가 있습니다. 첫 번째는 특정 기사의 요지를 파악하기 위해 사용자가 훑어보는 헤드라인 및 섹션과 같은 컨텐츠입니다. 두 번째는 독자적으로 설 수 있고 사용자 경험을 향상시키는 데 사용되는 작은 콘텐츠입니다. 우리가 염두에 두고 있는 한 가지 훌륭한 예는 Slack의 "여러 사람이 타이핑하고 있습니다.." 비트입니다. (Slack은 훌륭하게 작성된 마이크로컨텐츠로 가득 차 있지만).

같은 채널에 3명 이상의 사용자가 동시에 입력할 때 해당 비트가 트리거됩니다. 현재 입력하는 사람들의 목록을 인쇄하는 대신 Slack은 이 지루한 정보를 가져와 재미를 더합니다. 토론이 정말 뜨거워지기 시작했고 그것은 보여줍니다. 제품 문서(응용 프로그램 메시지가 그 일부입니다. 아니요?)가 사람들이 당신에 대해 이야기하게 만들고 위와 같은 재미있는 밈을 만드는 방법에 대한 훌륭한 예입니다.

REST API

REST API 문서화는 그 자체로 별도의 기술입니다. 모든 기술 문서와 마찬가지로 정의의 간결성, 명확성 및 단순성을 목표로 해야 합니다. REST API에는 고유한 형식과 복잡성이 있기 때문에 Tom Johnson의 I'd Later Be Writing 블로그에서 API 문서화를 위한 훌륭한 가이드를 공부하는 것만큼 나쁠 것은 없습니다.

협업 및 계획 문서

궁극적으로 문서는 제품 설계의 일부여야 합니다. 따라서 소프트웨어 주기에 추가 파이프라인이 있는 것으로 접근해야 합니다. 이는 소프트웨어 리포지토리를 사용하여 최신 문서 버전을 저장하고, 버그/이슈 추적기를 사용하여 작업 및 문제를 모니터링하고, 로드맵에 대한 문서 프로젝트 계획을 포함하고, 마지막으로 중요한 것은 다른 사람들과의 협업을 의미합니다. 시작하는 방법에 대한 대략적인 개요는 다음과 같습니다.

사용자가 알고 싶어하는 모든 것과 텍스트를 작성해야 하는 영역을 기록합니다.
모든 것이 준비되면 범주로 그룹화하고 문서 제목을 만듭니다.
제목, 설명, 대상 독자, 미디어(문서의 형식), 길이, 소요 시간 등과 같은 사항을 자세히 설명하는 각 문서에 대한 사양을 작성하십시오.
문서 사양의 견적을 프로젝트 계획에 추가합니다.

제품 문서는 모든 영역에 걸쳐 있으므로 조직 내에서 다양한 사람들과 작업해야 한다는 것이 거의 확실합니다. 이 모든 일이 어떻게 진행될 것인지에 대한 일종의 절차에 대해 앉아서 동의하는 것이 좋습니다. 모든 프로젝트에서와 마찬가지로 기술 지원을 제공할 이해 관계자와 변경 사항을 검토 및 편집할 이해 관계자를 식별해야 합니다.

프로세스의 다른 단계가 있어야 합니다. 여기에는 정보가 수집되는 위치, 문서가 작성된 시간, 문학적 교정, 기술적인 설명, 출판 등을 위한 준비가 된 시간이 표시되어야 합니다. 문학적, 기술적, 내용 관련 주석의 차이점을 강조합니다. 예를 들어, 팀 리더에게 문서에 대한 의견을 말하도록 요청하면 기술적으로 관련된 정보 대신 문법과 구두점에 대한 불만이 나옵니다.

폐쇄

제품 문서는 장기적으로 가치가 있는 자산입니다. 고객에게 가치를 제공합니다. 예를 들어 Stripe의 API 문서처럼 사람들이 포럼에서 이에 대해 열광할 정도로 훌륭할 수도 있습니다. 이는 참여를 구축하고 브랜드와 제품을 자연스럽고 강력한 방식으로 광고합니다. 독창적인 마이크로컨텐츠와 결합하면 Mike Puterbaugh가 제품 문서가 "마케팅의 비밀 무기"라고 말한 의미를 달성할 수 있습니다.