다음을 통해 공유


설명서 지침 - MRTK2

MRTK

이 문서에서는 MRTK(Mixed Reality Toolkit)에 대한 설명서 지침 및 표준을 간략하게 설명합니다. 설명서 작성 및 생성의 기술적 측면을 소개하고, 일반적인 문제를 강조 표시하고, 권장되는 쓰기 스타일을 설명합니다.

페이지 자체는 예제로 사용되므로 의도한 스타일과 설명서의 가장 일반적인 태그 기능을 사용합니다.


기능 및 태그

이 섹션에서는 자주 필요한 기능에 대해 설명합니다. 작동 방식을 확인하려면 페이지의 소스 코드를 확인합니다.

  1. 번호 매기기 목록
    1. 3개 이상의 선행 공백이 있는 중첩된 번호 매기기 목록
    2. 코드의 실제 숫자는 관련이 없습니다. 구문 분석에서는 올바른 항목 번호 설정을 처리합니다.
  • 글머리 기호 목록
    • 중첩된 글머리 기호 목록
  • **이중 별표**가 있는 굵은 텍스트
  • _밑줄_ 또는 *단일 별표*가 있는 기울임꼴텍스트
  • '백쿼트 사용' 문장 내의 텍스트 highlighted as code
  • 문서 페이지 MRTK 설명서 지침에 대한 링크
  • 페이지 내의 앵커에 대한 링크 앵커는 공백을 대시로 바꾸고 소문자로 변환하여 형성됩니다.

코드 샘플의 경우 세 개의 백틱이 '''인 블록을 사용하고 구문 강조 표시를 위한 언어로 csharp 를 지정합니다.

int SampleFunction(int i)
{
   return i + 42;
}

문장 use a single backtick내에서 코드를 언급하는 경우.

Todos

시간이 지남에 따라 이러한 TODO(예: 코드 TODO)가 누적되고 업데이트 방법 및 손실 이유에 대한 정보가 누적되는 경향이 있으므로 문서에서 TODO를 사용하지 마세요.

TODO를 추가해야 하는 경우 다음 단계를 수행합니다.

  1. TODO의 컨텍스트를 설명하는 새 문제를 Github에 제출하고 다른 기여자 이해하고 TODO를 해결할 수 있는 충분한 배경을 제공합니다.
  2. 문서의 할 일에서 문제 URL을 참조합니다.

<-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: 문제에 대한 간략한 흐림 -->

강조 표시된 섹션

독자에게 특정 점을 강조 표시하려면 [!> 참고] , > [! 경고] , 및 > [! 중요] 다음 스타일을 생성합니다. 일반적인 포인트에 대한 메모와 특별한 관련 사례에 대해서만 경고/중요 지점을 사용하는 것이 좋습니다.

참고

메모의 예

경고

경고의 예

중요

중요한 주석의 예

페이지 레이아웃

소개

기본 챕터 제목 바로 뒤의 부분은 장의 내용을 간단히 소개하는 역할을 해야 합니다. 이 작업을 너무 오래 수행하지 말고 하위 헤드라인을 추가합니다. 이렇게 하면 섹션에 연결할 수 있으며 책갈피로 저장할 수 있습니다.

본문

2단계 및 3단계 헤드라인을 사용하여 나머지를 구성합니다.

미니 섹션

눈에 띄는 블록에 굵은 텍스트 줄을 사용합니다. 우리는 어떤 시점에서 네 수준의 헤드 라인으로 이것을 대체 할 수 있습니다.

'참고 항목' 섹션

대부분의 페이지는 참조라는 챕터로 끝나야 합니다. 이 챕터는 이 항목과 관련된 페이지에 대한 링크의 글머리 기호 목록일 뿐입니다. 이러한 링크는 적절한 경우 페이지 텍스트 내에 나타날 수도 있지만 필수는 아닙니다. 마찬가지로 페이지 텍스트에는 기본 항목과 관련이 없는 페이지에 대한 링크가 포함될 수 있습니다. 이 링크는 참고 항목 목록에 포함되어서는 안 됩니다. 링크 선택에 대한 예제는 이 페이지의 ''See also'' 챕터를 참조 하세요.

목차(TOC)

Toc 파일은 MRTK github.io 설명서에서 탐색 모음을 생성하는 데 사용됩니다. 새 설명서 파일이 추가되면 설명서 폴더의 toc.yml 파일 중 하나에 해당 파일에 대한 항목이 있는지 확인합니다. toc 파일에 나열된 문서만 개발자 문서의 탐색에 표시됩니다. 기존 toc 파일에 연결하여 탐색의 해당 부분에 하위 섹션으로 추가할 수 있는 설명서 폴더의 모든 하위 폴더에 대한 toc 파일이 있을 수 있습니다.

스타일

쓰기 스타일

엄지 손가락의 일반적인 규칙 : 전문가 소리하려고합니다. 이는 일반적으로 '대화형 톤'을 피하는 것을 의미합니다. 또한 과장과 감각주의를 피하려고합니다.

  1. (지나치게) 재미있게 하려고 하지 마십시오.
  2. 'I'를 쓰지 마세요.
  3. '우리'를 피하십시오. 일반적으로 'MRTK'를 대신 사용하여 쉽게 변경할 수 있습니다. 예: "이 기능을 지원합니다." -> "MRTK에서 이 기능을 지원합니다." 또는 "다음 기능이 지원됩니다...".
  4. 마찬가지로 ,'당신'을 피하려고합니다. 예: "이 간단한 변경으로 셰이더를 구성할 수 있습니다!" -> "셰이더는 약간의 노력으로 구성할 수 있습니다."
  5. 'sloppy phrases'를 사용하지 마세요.
  6. 지나치게 흥분 소리를 방지, 우리는 아무것도 판매 할 필요가 없습니다.
  7. 마찬가지로, 지나치게 극적인 것을 피하십시오. 느낌표는 거의 필요하지 않습니다.

대문자 표시

  • 헤드라인에 문장 대/소문자를 사용합니다. Ie. 첫 글자와 이름을 대문자로 표시하지만 그 외에는 아무 것도 사용할 수 없습니다.
  • 다른 모든 항목에 일반 영어를 사용합니다. 즉, 해당 컨텍스트에서 특별한 의미를 갖는 경우에도 임의의 단어를 대문자로 표시 하지 않습니다. 특정 단어를 강조 표시하려면 기울임꼴 텍스트를 선호 합니다. 아래를 참조하세요.
  • 링크가 문장(기본 설정 방법)에 포함된 경우 표준 장 이름은 항상 대문자를 사용하므로 텍스트 내부에 임의의 대문자가 없는 규칙을 위반합니다. 따라서 사용자 지정 링크 이름을 사용하여 대문자를 수정합니다. 예를 들어 경계 컨트롤 설명서에 대한 링크는 다음과 같습니다.
  • Unity와 같은 이름을 대문자로 표시 합니다.
  • Unity 편집기를 작성할 때 "편집기"를 대문자로 표시하지 마세요.

강조 및 강조 표시

단어를 강조 표시하거나 강조 표시하여 굵게 만들거나 기울임꼴로 만드는 두 가지 방법이 있습니다. 굵은 텍스트의 효과는 굵은 텍스트가 튀어 나오 므로 텍스트를 건너 들이거나 페이지 위로 스크롤하는 동안 쉽게 알 수 있다는 것입니다. 굵게는 사람들이 기억해야 하는 문구를 강조 표시하면 좋습니다. 그러나 일반적으로 방해가 되므로 굵은 텍스트를 거의 사용하지 않습니다.

종종 논리적으로 함께 속한 항목을 '그룹화'하거나 특별한 의미가 있기 때문에 특정 용어를 강조 표시하려고 합니다. 이러한 작업은 전체 텍스트에서 눈에 띄지 않아도 됩니다. 기울임꼴 텍스트를 간단한 방법으로 사용하여 항목을 강조 표시합니다.

마찬가지로 파일 이름, 경로 또는 메뉴 항목이 텍스트에 언급된 경우 주의가 산만하지 않고 논리적으로 그룹화되도록 기울임꼴로 만드는 것을 선호합니다.

일반적으로 불필요한 텍스트 강조 표시를 방지합니다. 특수 용어는 독자가 인식하도록 한 번 강조 표시할 수 있으며, 텍스트 전체에서 이러한 강조 표시를 반복하지 마세요. 더 이상 목적이 없고 산만해질 뿐입니다.

메뉴 항목 언급

사용자가 클릭해야 하는 메뉴 항목을 언급할 때 현재 규칙은 프로젝트 > 파일 > 리프 만들기 > 입니다.

가능한 한 많은 유용한 링크를 다른 페이지에 삽입하지만 각 링크는 한 번만 삽입합니다. 독자가 페이지의 모든 링크를 클릭하는 경우 동일한 페이지가 20번 열리면 얼마나 성가신지 생각해 보세요.

문장에 포함된 링크를 선호합니다.

  • BAD: 지침이 유용합니다. 자세한 내용은 이 장을 참조하세요.
  • GOOD: 지침 이 유용합니다.

외부 링크가 오래되거나 저작권이 있는 콘텐츠를 포함할 수 있습니다.

링크를 추가할 때도 참조 섹션에 링크가 나열되어야 하는지 여부를 고려 합니다 . 마찬가지로 새 페이지에 대한 링크를 연결된 페이지에 추가해야 하는지 여부를 검사.

이미지/스크린샷

드물게 스크린샷을 사용합니다. 설명서에서 이미지를 유지 관리하는 것은 많은 작업이며, 작은 UI 변경으로 인해 많은 스크린샷이 오래되었습니다. 다음 규칙은 유지 관리 작업을 줄입니다.

  1. 텍스트에 설명될 수 있는 항목에는 스크린샷을 사용하지 마세요. 특히 속성 이름 및 값을 표시하기 위한 목적으로만 속성 표를 스크린샷으로 표시하지 않습니다 .
  2. 표시된 내용과 관련이 없는 항목을 스크린샷에 포함하지 마세요. instance 경우 렌더링 효과가 표시되면 뷰포트의 스크린샷을 만들지만 주변의 UI는 제외합니다. 일부 UI를 표시하고 중요한 부분만 이미지에 있도록 창을 이동합니다.
  3. 스크린샷 UI를 포함하는 경우 중요한 부분만 표시합니다. 예를 들어 도구 모음의 단추에 대해 이야기할 때 중요한 도구 모음 단추를 표시하는 작은 이미지를 만들지만 주변의 모든 것을 제외합니다.
  4. 재현하기 쉬운 이미지만 사용합니다. 즉, 표식이나 하이라이트를 스크린샷에 그리지 마세요. 첫째, 어쨌든 이러한 모양에 대한 일관된 규칙은 없습니다. 둘째, 이러한 스크린샷을 재현하는 것은 추가적인 노력입니다. 대신 텍스트의 중요한 부분을 설명합니다. 이 규칙에는 예외가 있지만 드물다.
  5. 물론 애니메이션 GIF를 다시 만드는 것은 훨씬 더 많은 노력입니다. 시간이 끝날 때까지 다시 만들 책임이 있거나 사람들이 그 시간을 보내고 싶지 않다면 그것을 던질 것으로 기대합니다.
  6. 아티클의 이미지 수를 낮게 유지합니다. 종종 좋은 방법은 모든 것을 보여 주는 일부 도구의 전체 스크린샷을 만들고 나머지를 텍스트로 설명하는 것입니다. 이렇게 하면 필요할 때 스크린샷을 쉽게 바꿀 수 있습니다.

몇 가지 다른 측면은 다음과 같습니다.

  • 스크린샷에 대한 편집기 UI는 모든 사용자가 어두운 테마에 액세스할 수 있는 것은 아니므로 밝은 회색 테마 편집기를 사용해야 하며 가능한 한 일관되게 유지하려고 합니다.
  • 대부분의 모니터에 잘 표시되므로 기본 이미지 너비는 500픽셀입니다. 너무 많이 벗어나지 않도록 노력하십시오. 너비가 800픽셀이어야 합니다.
  • UI 스크린샷에 PNG를 사용합니다.
  • 3D 뷰포트 스크린샷에 PNG 또는 JPG를 사용합니다. 압축 비율보다 품질을 선호합니다.

구성 요소 속성 목록

속성 목록을 문서화할 때 굵은 텍스트를 사용하여 속성 이름을 강조 표시한 다음 줄 바꿈 및 일반 텍스트를 사용하여 설명합니다. 하위 장 또는 글머리 기호 목록을 사용하지 마세요.

또한 마침표로 모든 문장을 완료하는 것을 잊지 마세요.

페이지 완성 검사 목록

  1. 이 문서의 지침이 준수되었는지 확인합니다.
  2. 문서 구조를 찾아보고 다른 페이지의 참고 항목 섹션에서 새 문서를 언급할 수 있는지 확인 합니다.
  3. 사용 가능한 경우 기술적인 정확성을 위해 페이지에 대한 증명 읽기 항목에 대한 지식이 있는 사람이 있어야 합니다.
  4. 스타일 및 서식 지정을 위해 다른 사람이 페이지를 교정하여 읽게 합니다. 이 항목은 이 항목에 익숙하지 않은 사람이 될 수 있으며, 설명서가 얼마나 이해하기 쉬운지에 대한 피드백을 받는 것이 좋습니다.

원본 설명서

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) 파일이 포함됩니다. 지정된 기능 영역의 크기 및/또는 복잡성에 따라 제공된 기능당 최대 하나씩 추가 파일이 필요할 수 있습니다.

기능이 추가되거나 사용량이 변경되면 개요 설명서를 제공해야 합니다.

이 설명서의 일부로 일러스트레이션을 비롯한 방법 섹션을 제공하여 시작의 기능 또는 개념을 접하는 고객을 지원해야 합니다.

디자인 설명서

Mixed Reality 완전히 새로운 세계를 만들 수있는 기회를 제공합니다. 이 중 일부는 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 파일을 편집하는 데 유용한 도구입니다.

설명서를 작성할 때 다음 두 확장을 설치하는 것도 좋습니다.

  • docs Markdown Extension for Visual Studio Code - Alt+M을 사용하여 문서 작성 옵션 메뉴를 표시합니다.

  • 코드 맞춤법 검사기 - 철자가 틀린 단어에는 밑줄이 그어집니다. 철자가 틀린 단어를 마우스 오른쪽 단추로 클릭하면 변경하거나 사전에 저장할 수 있습니다.

이 두 가지 모두 Microsoft에서 게시한 Docs 제작 팩에 패키지되어 있습니다.

추가 정보