WordPress 플러그인 및 테마 문서화

게시 됨: 2017-03-17

문서화는 일반적으로 문제가 있고 신속하게 답변이 필요한 경우에만 감사하는 것입니다. 이 기사에서는 WordPress 자산에 대한 문서 작성이 WordPress 개발자로서의 업무에 중요한 이유와 제공하는 테마 및 플러그인의 품질에 대해 설명합니다.

문서화가 중요한 이유는 무엇입니까?

프로젝트, 자산 또는 제품에 대한 최신 문서 세트를 유지하는 것은 여러 가지 이유로 중요합니다.

첫째, 2개월 전에 만들고 그 이후로 만지지 않은 것을 보고 그것이 무엇을 의미하는지 전혀 모르는 것은 흔한 경험입니다. 당신이 그것을 개발할 때 당신은 모든 것을 머리 속에 가지고 있지만 미래에는 그 이해가 없을 것입니다. 따라서 인라인 코드 주석을 사용하거나 Markdown에서 일반 텍스트 메모를 작성하면 미래의 자신을 혼란에서 구하는 데 큰 도움이 됩니다.

둘째, 자산을 문서화하는 것은 다른 WordPress 개발자에게 도움이 됩니다. 그리고 이것은 당신이 고독한 프리랜서인 경우에도 의미가 있습니다. 그들은 해당 자산을 사용해야 하거나 자산을 유지 관리 및/또는 업데이트하도록 요청받을 것입니다. 주변에 지원을 제공하거나 어려운 부분을 설명하지 않는 다른 사람이 작성한 문서화되지 않은 코드를 사용해야 하는 것은 매우 실망스러운 일입니다.

마지막으로, 문서에는 제품에 "광택된" 모양이 추가되어 고객이 귀하를 더 사랑하게 될 것입니다.

효과적인 문서화를 위한 5가지 원칙

테크니컬 라이팅은 그 자체로 하나의 학문이며 명확하고 모호하지 않은 방식으로 기술 정보를 전달하는 데 사용됩니다. (예를 들어, 컴퓨터에만 국한되지 않고 변호사와 의사도 고유한 기술 언어를 사용합니다.) 이러한 이유로 기술적인 문서로 간주되는 문서는 일반적으로 특정 스타일을 따르고 일련의 규칙을 따릅니다.

제품에 대한 효과적인 문서를 작성할 수 있도록 가장 중요한 5가지를 살펴보겠습니다!

일반적으로 글을 쓸 때보다 적은 수의 단어를 사용하는 것을 선호합니다. 모든 단어에는 목적이 있어야 합니다. 직접적이고 단순해야 합니다. 문서는 일반적으로 사람이 곤경에 처해 신속하게 해결책을 찾고자 할 때 필요합니다. 예를 들어, "객체 Q를 파괴하지 못하면 메모리 누수가 발생합니다"와 같은 문장이 "객체 Q를 파괴하지 못하면 메모리 누수 가 발생 합니다"와 같은 문장이 더 좋습니다.
수동태 대신 능동태 사용 선호: "오른쪽 상단의 버튼을 클릭 해야 합니다." 대신 "오른쪽 상단의 버튼을 클릭 하세요." 능동태를 사용하면 누가 무엇을 하는지에 대한 모호함이 사라집니다. 수동태는 주제가 아닌 대상에 집중해야 할 때만 사용됩니다(예: Pressidium의 플랫폼은 보안을 염두에 두고 구축 됨) .
개념을 설명해야 하는 경우 설명 언어를 사용하고 자습서와 같은 단계별 절차를 설명해야 하는 경우 명령형 언어를 사용합니다.
순서가 없는 항목을 나열해야 할 때는 글머리 기호 목록을 사용하고, 순서가 중요한 경우 번호 매기기 목록을 사용합니다.
지침을 발표하기 전에 지침을 직접 테스트했는지 확인하십시오!

WordPress 플러그인 문서화

WordPress 플러그인은 다른 소프트웨어와 같습니다. 특정 기능을 제공하고 설치가 필요하며 때로는 문제 해결도 필요합니다. 아무리 단순하더라도 모든 사용자가 동일한 기술 전문 지식을 공유하는 것은 아니므로 적절한 양의 문서를 제공하는 것이 좋습니다.

wordpress.org에 WordPress 플러그인을 게시하면 설치 지침, 스크린샷, FAQ, Changelog까지 넣을 수 있습니다! 유용하고 양질의 정보로 채우는 것이 플러그인을 더 유명하게 만드는 열쇠입니다.

궁극적으로 사용자가 플러그인을 다운로드하고 웹사이트를 방문하게 하는 설득력 있고 유용한 설명을 작성하십시오.
플러그인이 브라우저에서 어떻게 보이는지 보여주는 스크린샷 외에 플러그인의 각 구성 항목을 설명하는 주석이 달린 스크린샷을 추가하십시오.
진부하지 않은 질문을 FAQ에 넣으십시오. 이상한 경우를 발견하는 좋은 방법은 컴퓨터에 익숙하지 않은 친구에게 플러그인을 사용하도록 요청하는 것입니다.
업데이트되고 잘 작성된 변경 로그가 있습니다. 간결하고 비밀스러운 한 줄짜리 글은 절대 금물이며 사용자를 진정으로 돌보지 않는다는 것을 보여줍니다.
플러그인의 코드가 주석 처리가 잘 되어 있고 모범 소프트웨어 사례와 공식 코딩 표준을 따르는지 확인하십시오.

막혀서 영감이 필요하면 소규모 연구를 수행하고 덜 사용되는 플러그인과 비교하여 수십만 개의 설치가 있는 인기 있는 플러그인에서 텍스트가 어떻게 작성되는지 확인하십시오.

WordPress 테마 문서화

WordPress 테마를 문서화하는 것은 완전히 다른 문제입니다. WordPress 테마의 가장 일반적인 문제는 어떤 섹션이 어떤 시각적 요소에 해당하는지 모르는 것입니다. 모든 사람이 CSS에 능숙한 것은 아닙니다.

해당 설명과 함께 CSS의 모든 섹션에 대한 계층 구조를 만듭니다.
각 섹션에 대해 작은 예와 함께 각 기능을 자세히 설명하는 주석이 달린 스크린샷을 추가하십시오. 사용자가 지시를 따라야 하는 작업을 수행하는 방법을 보여줄 때 능동태와 명령형 언어를 사용하는 것을 잊지 마십시오.
css_doc과 같은 도구를 사용하면 도움이 됩니다. 이것은 JavaDoc 스타일의 문서를 생성하고 게시할 수 있습니다.
때로는 코드 주석이 충분하지 않고 CSS 테마에 대한 스타일 가이드 문서를 만들어야 합니다. 스타일 가이드 문서는 요소가 어떻게 보여야 하고 어떤 경우에 사용해야 하는지 설명합니다. 일관성을 유지하고 공동 작업을 더 쉽게 만듭니다. Google의 이 예를 참조하세요.
Blueprint CSS와 같은 CSS 프레임워크를 사용합니다. 이것은 사용자 정의 가능한 그리드, 작동하는 기본 타이포그래피, 브라우저 CSS 재설정 등과 같은 도구 세트를 제공하여 개발에 도움이 될 것입니다.
다시 말하지만 공식 WordPress CSS 코딩 표준을 참조하는 것을 잊지 마십시오.