기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 설명서 개발 및 세부 조정
<a name="documentation-best-practices"></a>

설명서는 프로젝트 성공에 매우 중요합니다. 설명서는 코드 작동 방식을 설명할 뿐만 아니라 개발자가 애플리케이션의 특성과 기능을 더 잘 이해하는 데도 도움이 됩니다. 고품질 설명서를 개발하고 개선하면 소프트웨어 개발 프로세스를 강화하고, 고품질 소프트웨어를 유지하고, 개발자 간의 지식 전달에 도움이 될 수 있습니다.

설명서에는 코드 내 문서화와 코드에 대한 지원 문서라는 두 가지 범주가 있습니다. 코드 내 문서는 주석 형식입니다. 코드에 대한 지원 문서는 README 파일 및 외부 문서일 수 있습니다. 코드 자체를 이해하기 쉽기 때문에 개발자가 설명서를 오버헤드로 생각하는 것은 드문 일이 아닙니다. 소규모 프로젝트의 경우에는 그럴 수 있지만, 여러 팀이 참여하는 대규모 프로젝트에서는 설명서가 매우 중요합니다.

코드 작성자는 기능을 잘 이해하고 있으므로 설명서를 작성하는 것이 가장 좋습니다. 개발자는 별도의 지원 설명서를 유지 관리해야 하는 추가 오버헤드로 인해 어려움을 겪을 수 있습니다. 이 문제를 해결하기 위해 개발자는 코드에 주석을 추가하면 해당 주석을 자동으로 추출하여 모든 버전의 코드와 문서를 동기화할 수 있습니다.

개발자가 코드에서 주석을 추출하고 이에 대한 문서를 생성하는 데 도움이 되는 다양한 도구가 있습니다. 이 가이드에서는 TypeDoc을 AWS CDK 구문에 대한 기본 도구로 중점적으로 다룹니다.

## AWS CDK 구문에 코드 설명서가 필요한 이유
<a name="code-docs-constructs"></a>

AWS CDK 일반적인 구성은 조직의 여러 팀에서 생성하며 다양한 팀 간에 공유하여 사용합니다. 좋은 설명서는 구성 라이브러리 소비자가 최소한의 노력으로 구성을 쉽게 통합하고 인프라를 구축하는 데 도움이 됩니다. 모든 문서를 동기화하는 것은 큰 작업입니다. TypeDoc 라이브러리를 사용하여 추출되는 코드 내에 문서를 보관하는 것이 좋습니다.

## AWS Construct Library에서 TypeDoc 사용
<a name="typedoc-constructs"></a>

TypeDoc은 TypeScript를 위한 문서 생성기입니다. TypeDoc을 사용하여 TypeScript 소스 파일을 읽고, 해당 파일의 주석을 구문 분석한 다음, 코드에 대한 설명서가 포함된 정적 사이트를 생성할 수 있습니다.

다음 코드는 TypeDoc을 AWS Construct Library와 통합한 다음의 `package.json` 파일에 다음 패키지를 추가하는 방법을 보여줍니다`devDependencies`.

```
{

  "devDependencies": {
   
    "typedoc-plugin-markdown": "^3.11.7",
    "typescript": "~3.9.7"
  },
  
}
```

CDK 라이브러리 폴더에서 `typedoc.json`을 추가하려면 다음 코드를 사용하세요.

```
{
    "$schema": "https://typedoc.org/schema.json",
    "entryPoints": ["./lib"],
}
```

README 파일을 생성하려면 AWS CDK 구문 라이브러리 프로젝트의 루트 디렉터리에서 `npx typedoc` 명령을 실행합니다.

다음 샘플 문서는 TypeDoc에서 생성됩니다.

![샘플 TypeDoc 문서](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/best-practices-cdk-typescript-iac/images/sample_typedoc_1.png)


TypeDoc 통합 옵션에 대한 자세한 내용은 TypeDoc 설명서의 [Doc Comments](https://typedoc.org/guides/doccomments/)를 참조하세요.