다음을 통해 공유

PowerShell Cmdlet에 대한 도움말 작성

  • 아티클

PowerShell cmdlet은 유용할 수 있지만 도움말 항목에서 cmdlet의 기능과 사용 방법을 명확하게 설명하지 않으면 cmdlet이 사용되지 않거나 더 나쁜 경우 사용자에게 불만을 줄 수 있습니다. XML 기반 cmdlet 도움말 파일 형식은 일관성을 향상하지만 유용한 도움말에는 훨씬 더 많은 것이 필요합니다.

cmdlet 도움말을 작성한 적이 없는 경우 다음 지침을 검토합니다. cmdlet 도움말 항목을 작성하는 데 필요한 XML 스키마는 다음 섹션에 설명되어 있습니다. Cmdlet 도움말 파일만들기로 시작합니다. 이 항목에는 최상위 XML 노드에 대한 설명이 포함되어 있습니다.

Cmdlet 도움말에 대한 지침 작성

잘 쓰기

잘 작성된 토픽을 대체하는 것은 없습니다. 전문 작가가 아닌 경우 도움을 줄 작가나 편집자를 찾아보세요. 또 다른 대안은 도움말 텍스트를 Microsoft Word에 복사하고 문법 및 맞춤법 검사를 사용하여 작업을 개선하는 것입니다.

간단히 작성

간단한 단어와 구를 사용합니다. 전문 용어를 사용하지 마십시오. 많은 독자는 외국어 사전과 도움말 항목만 갖추고 있다고 생각해 보세요.

일관되게 작성

관련 cmdlet에 대한 도움말은 유사해야 합니다(예: Get-Content 및 Set-Content). Force 및 InputObject같은 표준 매개 변수에 대한 표준 설명을 사용합니다. (핵심 cmdlet에 대한 도움말에서 복사합니다.) 표준 용어를 사용합니다. 예를 들어 "argument"가 아닌 "parameter"를 사용하고 "command" 또는 "command-let"이 아닌 "cmdlet"을 사용합니다.

동사를 사용하여 시냅스 시작

개요 필드는 cmdlet이 수행하는 작업이나 작동 방식을 알려주지 않습니다. 동사는 이 cmdlet이 요구 사항을 충족하는지 사용자에게 알리는 작업 기반 문을 만듭니다. "get", "create" 및 "change"와 같은 간단한 동사를 사용합니다. "modify"와 같이 모호하고 멋진 단어가 될 수 있는 "set"을 피하십시오.

개체에 포커스

대부분의 "get" cmdlet은 무언가를 표시하지만 기본 함수는 개체를 가져오는 것입니다. 도움말에서 사용자가 기본 표시가 여러 가지 중 하나임을 이해하고 검색한 개체의 메서드와 속성을 다양한 방법으로 사용할 수 있도록 개체에 집중합니다.

자세한 설명 작성

자세한 설명에서 cmdlet이 수행할 수 있는 모든 작업을 간략하게 나열합니다. 주 함수가 하나의 속성을 변경하지만 cmdlet이 모든 속성을 변경할 수 있는 경우 자세한 설명에 나열합니다.

기존 구문 사용

Windows 및 Unix 명령줄 도움말에 공통적인 표준 Backus-Naur 형식을 사용합니다.

매개 변수 값에 Microsoft .NET 형식 사용

매개 변수 값의 자리 표시자(구문 및 매개 변수 설명)에는 매개 변수가 수락할 개체의 .NET Framework 형식이 표시됩니다. PowerShell 팀은 사용자에게 .NET Framework에 대해 교육하는 데 도움이 되는 이 규칙을 개발했습니다.

전체 매개 변수 설명 작성

매개 변수 설명은 매개 변수가 수행하는 작업(효과)과 매개 변수 값에 대해 입력해야 하는 항목의 두 가지를 사용자에게 알려야 합니다.

실제 예제 작성

예제에서는 모든 매개 변수를 사용하는 방법을 보여 주지만 가장 중요한 것은 실제 작업에서 cmdlet을 사용하는 방법을 보여주는 것입니다. 간단한 예제로 시작하고 점점 더 복잡한 예제를 작성합니다. 마지막 예제에서는 파이프라인에서 cmdlet을 사용하는 방법을 보여 주세요.

메모 필드 사용

메모 필드를 사용하여 사용자가 cmdlet을 이해해야 하는 개념을 설명합니다. 사용자가 일반적인 오류를 방지하는 데 도움이 되도록 메모를 사용할 수도 있습니다. URL이 변경되면 사용하지 마세요. 대신 검색할 사용자 용어를 제공합니다.

도움말 테스트

코드를 테스트하는 것처럼 도움말을 테스트합니다. 친구와 동료가 도움말 콘텐츠를 읽고 피드백을 제공하도록 합니다. 뉴스 그룹에서 피드백을 요청할 수도 있습니다.

또한 참조하십시오