설명서 지침 - MRTK2
이 문서에서는 MRTK(Mixed Reality Toolkit)에 대한 설명서 지침 및 표준을 간략하게 설명합니다. 설명서 작성 및 생성의 기술적 측면을 소개하고, 일반적인 문제를 강조 표시하고, 권장되는 쓰기 스타일을 설명합니다.
페이지 자체는 예제로 사용되므로 의도한 스타일과 설명서의 가장 일반적인 태그 기능을 사용합니다.
기능 및 태그
이 섹션에서는 자주 필요한 기능에 대해 설명합니다. 작동 방식을 확인하려면 페이지의 소스 코드를 확인합니다.
- 번호 매기기 목록
- 앞에 공백이 3개 이상 있는 중첩된 번호 매기기 목록
- 코드의 실제 숫자는 관련이 없습니다. 구문 분석에서는 올바른 항목 번호 설정을 처리합니다.
- 글머리 기호 목록
- 중첩된 글머리 기호 목록
- **이중 별표**를 굵게 표시한 텍스트
- _underscore_ 또는 *단일 별표*가 있는 기울집 텍스트
- 'backquotes 사용' 문장 내의 텍스트
highlighted as code - 문서 페이지 MRTK 설명서 지침에 대한 링크
- 페이지 내의 앵커에 대한 링크입니다. 앵커는 공백을 대시로 대체하고 소문자로 변환하여 형성됩니다.
코드 샘플의 경우 세 개의 백틱 '''이 있는 블록을 사용하고 구문 강조 표시를 위한 언어로 csharp를 지정합니다.
int SampleFunction(int i)
{
return i + 42;
}
문장 use a single backtick내에서 코드를 언급하는 경우 .
TODO
시간이 지남에 따라 이러한 TODO(예: 코드 TODO)가 누적되고 업데이트 방법 및 손실 이유에 대한 정보가 누적되는 경향이 있으므로 문서에서 TODO를 사용하지 마세요.
TODO를 추가해야 하는 경우 다음 단계를 수행합니다.
- TODO 뒤에 있는 컨텍스트를 설명하는 Github에 새 문제를 제출하고 다른 기여자가 TODO를 이해하고 해결할 수 있는 충분한 배경을 제공합니다.
- 문서의 할 일에서 문제 URL을 참조합니다.
<-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: 이 문제에 대한 간략한 흐림>
강조 표시된 섹션
독자 > 에게 특정 점을 강조 표시하려면 [! 참고] , > [! 경고] 및 > [! 중요] - 다음 스타일을 생성합니다. 일반적인 지점에 대한 메모와 특수 관련 사례에 대해서만 경고/중요 지점을 사용하는 것이 좋습니다.
참고 항목
메모의 예
Warning
경고의 예
Important
중요한 주석의 예
페이지 레이아웃
소개
주 챕터 제목 바로 뒤의 부분은 챕터의 내용을 간단히 소개하는 역할을 해야 합니다. 너무 오래 하지 마십시오, 대신 하위 헤드 라인을 추가 합니다. 섹션에 연결할 수 있으며 책갈피로 저장할 수 있습니다.
본문
나머지를 구조화하려면 2단계 및 3단계 헤드라인을 사용합니다.
미니 섹션
눈에 띄는 블록에 굵은 텍스트 줄을 사용합니다. 우리는 어떤 시점에서 4 수준의 헤드 라인으로 이것을 대체 할 수 있습니다.
'참고 항목' 섹션
대부분의 페이지는 참조라는 장으로 끝나야 합니다. 이 챕터는 이 항목과 관련된 페이지에 대한 링크의 글머리 기호 목록일 뿐입니다. 이러한 링크는 적절한 경우 페이지 텍스트 내에 나타날 수도 있지만 필수는 아닙니다. 마찬가지로 페이지 텍스트에는 기본 항목과 관련되지 않은 페이지에 대한 링크가 포함될 수 있습니다. 참고 항목 목록에는 포함되지 않아야 합니다. 링크 선택에 대한 예제는 이 페이지의 ''See also'' 챕터를 참조하세요.
목차(TOC)
Toc 파일은 MRTK github.io 설명서에서 탐색 모음을 생성하는 데 사용됩니다. 새 설명서 파일이 추가되면 설명서 폴더의 toc.yml 파일 중 하나에 해당 파일에 대한 항목이 있는지 확인합니다. toc 파일에 나열된 문서만 개발자 문서의 탐색에 표시됩니다. 설명서 폴더의 모든 하위 폴더에 대한 toc 파일이 있을 수 있습니다. 이 파일은 기존 toc 파일에 연결하여 탐색의 해당 부분에 하위 섹션으로 추가할 수 있습니다.
스타일
쓰기 스타일
엄지 손가락의 일반적인 규칙 : 전문가 소리하려고합니다. 이는 일반적으로 '대화형 톤'을 피하는 것을 의미합니다. 또한 과장과 감각주의를 피하려고합니다.
- (지나치게) 재미하려고하지 마십시오.
- 'I'를 쓰지 마세요.
- '우리'를 피하십시오. 일반적으로 'MRTK'를 대신 사용하여 쉽게 변경할 수 있습니다. 예: "이 기능을 지원합니다." -> "MRTK에서 이 기능을 지원합니다." 또는 "다음 기능이 지원됩니다...".
- 마찬가지로,'당신'을 피하려고합니다. 예: "이 간단한 변경으로 셰이더를 구성할 수 있습니다!" -> "셰이더는 약간의 노력으로 구성할 수 있습니다."
- '단정한 구'를 사용하지 마세요.
- 지나치게 흥분 소리를 피하십시오, 우리는 아무것도 판매 할 필요가 없습니다.
- 마찬가지로, 지나치게 극적인 것을 피하십시오. 느낌표는 거의 필요하지 않습니다.
대문자 적용
- 제목에 문장 대/소문자를 사용합니다. 즉, 첫 글자와 이름을 대문자로 표시합니다.
- 다른 모든 항목에 일반 영어를 사용합니다. 즉 , 해당 컨텍스트에서 특별한 의미를 지니고 있더라도 임의의 단어를 대문자로 표시하지 않습니다. 특정 단어를 강조 표시하기 위해 기울기 텍스트를 선호합니다. 아래를 참조하세요.
- 링크가 문장에 포함되는 경우(기본 메서드) 표준 장 이름은 항상 대문자를 사용하므로 텍스트 내에서 임의의 대문자가 없는 규칙을 위반합니다. 따라서 사용자 지정 링크 이름을 사용하여 대문자를 수정합니다. 예를 들어 경계 컨트롤 설명서에 대한 링크는 다음과 같습니다.
- Unity와 같은 이름을 대문자로 지정합니다.
- Unity 편집기를 작성할 때는 "편집기"를 대문자로 사용하지 마세요.
강조 및 강조 표시
단어를 강조하거나 강조 표시하여 굵게 만들거나 기울임꼴로 만드는 두 가지 방법이 있습니다. 굵은 텍스트의 효과는 굵은 텍스트가 튀어 나오 므로 텍스트 조각을 건너 찌를 때 또는 페이지 위로 스크롤하는 동안 쉽게 알 수 있다는 것입니다. 굵게는 사람들이 기억해야 할 문구를 강조하는 데 좋습니다. 그러나 일반적으로 방해가 되므로 굵은 텍스트를 거의 사용하지 않습니다.
논리적으로 함께 속하는 항목을 '그룹화'하거나 특정 용어를 강조 표시하려는 경우가 많습니다. 특별한 의미가 있기 때문입니다. 이러한 항목은 전체 텍스트에서 눈에 띄지 않아도 됩니다. 기울광 텍스트를 경량 메서드로 사용하여 항목을 강조 표시합니다.
마찬가지로 파일 이름, 경로 또는 메뉴 항목이 텍스트에 언급된 경우 주의가 산만하지 않고 논리적으로 그룹화되도록 기울임꼴로 만드는 것을 선호합니다.
일반적으로 불필요한 텍스트 강조 표시를 방지합니다. 특수 용어는 더 이상 목적을 제공하지 않고 산만 할 때, 독자가 인식 할 수 있도록 한 번 강조 표시 할 수 있습니다, 텍스트 전체에 이러한 강조를 반복하지 마십시오.
메뉴 항목 언급
사용자가 클릭해야 하는 메뉴 항목을 언급할 때 현재 규칙은 다음과 같습니다. 프로젝트 > 파일 > 리프 만들기 >
링크
가능한 한 많은 유용한 링크를 다른 페이지에 삽입하지만 각 링크는 한 번만 삽입합니다. 읽기 프로그램이 페이지의 모든 링크를 클릭하는 경우 동일한 페이지가 20번 열리면 얼마나 성가신지 생각해 보십시오.
문장에 포함된 링크를 선호합니다.
외부 링크가 만료되거나 저작권이 있는 콘텐츠를 포함할 수 있습니다.
링크를 추가할 때 참조 섹션에도 링크가 나열 되어야 하는지 여부를 고려합니다. 마찬가지로 새 페이지에 대한 링크를 링크된 페이지에 추가해야 하는지 여부를 확인합니다.
이미지/스크린샷
스크린샷을 아쉽게 사용합니다. 설명서에서 이미지를 유지 관리하는 것은 많은 작업이며, 작은 UI 변경으로 많은 스크린샷이 오래될 수 있습니다. 다음 규칙은 유지 관리 작업을 줄입니다.
- 텍스트로 설명할 수 있는 항목에는 스크린샷을 사용하지 마세요. 특히 속성 이름 및 값을 표시하기 위한 목적으로만 속성 표를 스크린샷으로 표시하지 않습니다.
- 표시된 항목과 관련이 없는 항목을 스크린샷에 포함하지 마세요. 예를 들어 렌더링 효과가 표시되면 뷰포트의 스크린샷을 만들지만 주변의 UI는 제외합니다. 일부 UI를 표시하여 중요한 부분만 이미지에 있도록 창을 이동해 봅니다.
- 스크린샷 UI를 포함하는 경우 중요한 부분만 표시합니다. 예를 들어 도구 모음의 단추에 대해 이야기할 때 중요한 도구 모음 단추를 표시하는 작은 이미지를 만들지만 주변의 모든 것을 제외합니다.
- 재현하기 쉬운 이미지만 사용합니다. 즉, 표식이나 강조 표시를 스크린샷에 그리지 마세요. 첫째, 어쨌든 이러한 모양에 대한 일관된 규칙은 없습니다. 둘째, 이러한 스크린샷을 재현하는 것은 추가 작업입니다. 대신 텍스트의 중요한 부분을 설명합니다. 이 규칙에는 예외가 있지만 드물다.
- 물론 애니메이션 GIF를 다시 만드는 것은 훨씬 더 많은 노력입니다. 시간이 끝날 때까지 다시 만들 책임이 있거나 사람들이 그 시간을 보내고 싶지 않다면 그것을 던질 것으로 기대하십시오.
- 아티클의 이미지 수를 낮게 유지합니다. 종종 좋은 방법은 모든 것을 보여 주는 일부 도구의 전체 스크린샷을 만들고 나머지를 텍스트로 설명하는 것입니다. 이렇게 하면 필요한 경우 스크린샷을 쉽게 바꿀 수 있습니다.
몇 가지 다른 측면은 다음과 같습니다.
- 스크린샷용 편집기 UI는 모든 사용자가 어두운 테마에 액세스할 수 있는 것은 아니므로 밝은 회색 테마 편집기를 사용해야 하며 가능한 한 일관되게 유지하려고 합니다.
- 대부분의 모니터에 잘 표시되므로 기본 이미지 너비는 500픽셀입니다. 너무 많이 벗어나지 않도록 노력하십시오. 800픽셀 너비는 최대값이어야 합니다.
- UI 스크린샷에 PNG를 사용합니다.
- 3D 뷰포트 스크린샷에는 PNG 또는 JPG를 사용합니다. 압축 비율보다 품질을 선호합니다.
구성 요소 속성 목록
속성 목록을 문서화할 때 굵은 텍스트를 사용하여 속성 이름을 강조 표시한 다음 줄 바꿈과 일반 텍스트를 사용하여 설명합니다. 하위 장 또는 글머리 기호 목록을 사용하지 마세요.
또한 마침표로 모든 문장을 완료하는 것을 잊지 마세요.
페이지 완성 검사 목록
- 이 문서의 지침이 준수되었는지 확인합니다.
- 문서 구조를 찾아보고 다른 페이지의 참고 섹션 아래에 새 문서를 언급할 수 있는지 확인합니다.
- 사용 가능한 경우 기술적인 정확성을 위해 해당 항목에 대한 지식을 가진 사람이 페이지를 교정하여 읽어 보십시오.
- 스타일 및 서식 지정을 위해 다른 사용자가 페이지를 교정하여 읽게 합니다. 이 항목에 익숙하지 않은 사람이 될 수 있으며 설명서가 얼마나 이해하기 쉬운지에 대한 피드백을 얻는 것이 좋습니다.
원본 설명서
API 설명서는 MRTK 원본 파일에서 자동으로 생성됩니다. 이를 위해 원본 파일은 다음을 포함해야 합니다.
위의 코드 외에도 유지 관리, 버그 수정 및 사용자 지정 용이성을 허용하도록 코드를 주석으로 작성해야 합니다.
클래스, 구조체, 열거형 요약 블록
클래스, 구조체 또는 열거형이 MRTK에 추가되는 경우 해당 용도를 설명해야 합니다. 클래스 위의 요약 블록 형식을 사용합니다.
/// <summary>
/// AudioOccluder implements IAudioInfluencer to provide an occlusion effect.
/// </summary>
클래스 수준 종속성이 있는 경우 요약 바로 아래의 설명 블록에 문서화되어야 합니다.
/// <remarks>
/// Ensure that all sound emitting objects have an attached AudioInfluencerController.
/// Failing to do so will result in the desired effect not being applied to the sound.
/// </remarks>
클래스, 구조 또는 열거형에 대한 요약 없이 제출된 끌어오기 요청은 승인되지 않습니다.
속성, 메서드, 이벤트 요약 블록
속성, 메서드 및 이벤트(PME) 및 필드는 코드 표시 유형(퍼블릭, 프라이빗, 보호됨 및 내부)에 관계없이 요약 블록으로 문서화되어야 합니다. 설명서 생성 도구는 퍼블릭 및 보호된 기능만 필터링하고 게시하는 역할을 합니다.
참고: Unity 메서드(예: 절전 모드 해제, 시작, 업데이트)에는 요약 블록이 필요하지 않습니다 .
끌어오기 요청을 승인하려면 PME 설명서가 필요합니다 .
PME 요약 블록의 일부로 매개 변수 및 반환된 데이터의 의미와 목적이 필요합니다.
/// <summary>
/// Sets the cached native cutoff frequency of the attached low pass filter.
/// </summary>
/// <param name="frequency">The new low pass filter cutoff frequency.</param>
/// <returns>The new cutoff frequency value.</returns>
기능 소개 버전 및 종속성
API 요약 설명서의 일부로, 기능이 도입된 MRTK 버전에 대한 정보 및 모든 종속성을 설명 블록에 문서화해야 합니다.
종속성에는 확장 및/또는 플랫폼 종속성이 포함되어야 합니다.
/// <remarks>
/// Introduced in MRTK version: 2018.06.0
/// Minimum Unity version: 2018.0.0f1
/// Minimum Operating System: Windows 10.0.11111.0
/// Requires installation of: ImaginarySDK v2.1
/// </remarks>
직렬화된 필드
Unity의 도구 설명 특성을 사용하여 검사기에서 스크립트의 필드에 대한 런타임 설명서를 제공하는 것이 좋습니다.
구성 옵션이 API 설명서에 포함되도록 스크립트는 적어도 도구 설명 콘텐츠를 요약 블록에 포함 해야 합니다.
/// <summary>
/// The quality level of the simulated audio source (ex: AM radio).
/// </summary>
[Tooltip("The quality level of the simulated audio source.")]
열거형 값
정의 및 열거할 때 코드는 요약 블록을 사용하여 열거형 값의 의미를 문서화해야 합니다. 설명 블록은 필요에 따라 이해를 높이기 위해 추가 세부 정보를 제공하는 데 사용할 수 있습니다.
/// <summary>
/// Full range of human hearing.
/// </summary>
/// <remarks>
/// The frequency range used is a bit wider than that of human
/// hearing. It closely resembles the range used for audio CDs.
/// </remarks>
방법 설명서
Mixed Reality Toolkit의 많은 사용자는 API 설명서를 사용할 필요가 없습니다. 이러한 사용자는 미리 만들어진 재사용 가능한 프리팹 및 스크립트를 활용하여 환경을 만듭니다.
각 기능 영역에는 제공된 내용과 상당히 높은 수준에서 설명하는 하나 이상의 markdown(.md) 파일이 포함됩니다. 지정된 기능 영역의 크기 및/또는 복잡성에 따라 제공된 기능당 최대 1개까지 추가 파일이 필요할 수 있습니다.
기능이 추가되거나 사용량이 변경되면 개요 설명서를 제공해야 합니다.
이 설명서의 일부로 일러스트레이션을 비롯한 방법 섹션을 제공하여 고객이 새로운 기능 또는 개념을 시작할 수 있도록 지원해야 합니다.
디자인 설명서
혼합 현실은 완전히 새로운 세계를 만들 수있는 기회를 제공합니다. 이 중 일부는 MRTK와 함께 사용할 사용자 지정 자산을 만드는 것을 포함할 수 있습니다. 고객이 마찰을 없도록 하려면 구성 요소에서 아트 자산에 대한 서식 또는 기타 요구 사항을 설명하는 디자인 설명서를 제공해야 합니다.
디자인 설명서가 도움이 될 수 있는 몇 가지 예는 다음과 같습니다.
- 커서 모델
- 공간 매핑 시각화
- 소리 효과 파일
이 유형의 설명서는 권장되며 끌어오기 요청 검토 일부로 요청될 수 있습니다.
MS 개발자 사이트의 디자인 권장 사항 과 다를 수도 있습니다.
성능 참고 사항
몇 가지 중요한 기능은 성능 비용이 듭니다. 종종 이 코드는 구성 방법에 따라 매우 달라집니다.
예시:
When using the spatial mapping component, the performance impact will increase with the level of detail requested.
It is recommended to use the least detail possible for the desired experience.
성능 정보는 CPU 및/또는 GPU가 많은 구성 요소에 권장되며 끌어오기 요청 검토 일부로 요청될 수 있습니다. 적용 가능한 모든 성능 정보는 API 및 개요 설명서에 포함되어야 합니다.
호환성이 손상되는 변경
주요 변경 설명서는 각 기능 영역의 개별 breaking-changes.md 연결하는 최상위 파일 로 구성됩니다.
파일 breaking-changes.md 기능 영역에는 지정된 릴리스에 대해 알려진 모든 주요 변경 내용 목록과 이전 릴리스의 호환성이 손상되는 변경 기록이 포함됩니다.
예시:
Spatial sound breaking changes
2018.07.2
* Spatialization of the imaginary effect is now required.
* Management of randomized AudioClip files requires an entropy value in the manager node.
2018.07.1
No known breaking changes
2018.07.0
...
기능 수준 breaking-changes.md 파일에 포함된 정보는 각 새 MRTK 릴리스에 대한 릴리스 정보로 집계됩니다.
변경의 일부인 호환성이 손상되는 변경 내용은 끌어오기 요청의 일부로 문서화되어야 합니다 .
MarkDown 편집 도구
Visual Studio Code 는 MRTK 설명서의 일부인 markdown 파일을 편집하는 데 유용한 도구입니다.
설명서를 작성할 때 다음 두 확장을 설치하는 것도 좋습니다.
Visual Studio Code용 Docs Markdown 확장 - Alt+M을 사용하여 문서 작성 옵션 메뉴를 표시합니다.
Code Spell Checker - 오타가 났을 경우 밑줄을 추가합니다. 오른쪽 클릭으로 잘못 쓰인 단어를 수정하거나 사전에 저장할 수 있습니다.
이 두 가지 모두 Microsoft에서 게시한 Docs Authoring Pack에 패키지로 제공됩니다.