MSDN에서 docs.microsoft.com으로 .NET API 설명서 이동
이 게시물은 클라우드 + AI 사업부의 프로그램 관리자 Den Delimarsky가 작성했습니다.
11개 로캘의 모든 .NET Framework 설명서가 MSDN에서 docs.microsoft.com으로 마이그레이션이 완료된 것을 알려 드리게 되어 기쁩니다. 이 마이그레이션의 양과 규모를 이해하기 쉽게 설명하면 .NET Framework 콘텐츠는 9백만 개 이상의 API 설명서 또는 전체 MSDN 라이브러리 양의 20%에 해당합니다.
목표는 Microsoft가 제공하는 모든 .NET API를 찾고 탐색하고, 버전 관리 심층 지원을 포함하고, API 코드 샘플을 사용 및 실행하고, 자동화를 사용하여 API를 쉽게 업데이트할 수 있고, 커뮤니티 기여를 지원하는 통합되고 현대적인 일관된 환경을 제공하는 것입니다.
docs.microsoft.com에서는 다음에 이 환경을 사용할 수 있습니다.
- .NET Framework(버전 1.1~4.7.2)
- .NET Core(버전 1.0~2.1)
- .NET Standard(버전 1.0~2.0)
- Microsoft에서 제공하는 모든 .NET API, SDK, NuGet 패키지
.NET API 브라우저를 사용하여 한곳에서 모든 Microsoft .NET API 검색
API를 찾고 있는데 어디서 시작해야 할지 몰랐던 적이 있나요? 제품 및 버전 필터를 사용하여 필요한 API를 몇 초 안에 빠르게 찾을 수 있는 전용 API 검색 인덱스인 .NET API 브라우저를 빌드했습니다.
버전 관리 지원
더 이상 형식이 특정 버전의 .NET Framework 또는 Azure Storage NuGet 패키지에서 사용할 수 있는 멤버를 포함하고 있는지를 궁금해할 필요가 없습니다. API 브라우저 컨트롤에서 버전만 변경하면 콘텐츠가 적절하게 조정됩니다.
향상된 조직
콘텐츠의 왼쪽 테이블에서 네임스페이스 및 해당 네임스페이스 내의 엔터티 형식을 기준으로 콘텐츠가 그룹화됩니다. 예를 들어 클래스를 선택하면 속성, 필드, 메서드, 이벤트 등 해당 형식을 기준으로 엔터티가 그룹화되는 것을 볼 수 있습니다.
또는 .NET API 브라우저를 사용하여 검색할 수도 있고, 목차에서 특정 API 버전을 필터링하여 원하는 정확한 API를 쉽게 찾을 수도 있습니다.
고객들은 API 참조 페이지 내에서 API 다운로드, 설정 및 기타 유용한 설명서를 찾기 어려운 경우가 있다고 알려 주셨습니다. 아래 이미지에서 볼 수 있듯이 Azure .NET SDK는 문서와 참조 설명서를 모두 하나의 목차에 결합합니다.
직관적인 URL
원래 docs.microsoft.com을 시작했을 때 목표 중 하나는 명확하고 일관되며 직관적인 계층적 URL을 사용하는 것이었습니다. MSDN 사용을 돌이켜보면 일부 .NET URL은 다음과 같이 구조화되어 있었습니다.
https://msdn.microsoft.com/library/8kszeddc(v=vs.110).aspx
그냥 봐서는 이 콘텐츠가 무엇인지 이해하기가 정말 어려웠습니다.
이제 위의 링크가 다음과 같이 바뀝니다.
https://docs.microsoft.com/dotnet/api/system.array.sort
다음은 .NET의 URL을 일관되고 직관적으로 만들기 위한 URL 설명서의 규칙 중 일부에 불과합니다.
네임스페이스
패턴: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}
예: https://docs.microsoft.com/dotnet/api/system.collections.generic/
클래스
패턴: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}
예: https://docs.microsoft.com/dotnet/api/system.flagsattribute
메서드
패턴: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}.{method}
예: https://docs.microsoft.com/dotnet/api/system.decimal.add
예제 먼저
고객과의 인터뷰에서 거듭해서 들었던 한 가지는 품질이 뛰어나고 간결하며 기능적인 API 코드 예제의 중요성입니다. MSDN에서는 예제가 페이지 끝에 포함되어 있었기 때문에 일부 예제에서는 형식의 첫 번째 예제를 보려면 20번 이상 아래로 스크롤해야 했습니다. Docs에서는 아래와 같이 예제가 먼저 나옵니다.
MSDN과 마찬가지로 Docs도 C#, VB, F#, C++를 비롯한 모든 .NET 언어를 지원합니다.
브라우저에서 대화형으로 예제 실행
코드 작업을 할 때 가장 좋은 학습 방법은 실제로 코드를 작성하는 것입니다. 우리는 브라우저에서 바로 코드를 작성할 수 있도록 하고 싶었습니다. 1년 전에 Try .NET 기능을 출시했고, 한 해 동안 여러 문서에 이 기능을 통합했습니다. 앞으로 이 기능을 계속 더 많은 API 문서에 통합하여 페이지에서 나가지 않고 실험할 수 있도록 하겠습니다.
표준 자동 생성 도구에서 지원
docs.microsoft.com의 모든 API 설명서는 자동으로 생성되므로 전체 API 표면을 쉽게 문서화하고 업데이트 시간과 빈도를 몇 주에서 몇 분으로 크게 개선할 수 있습니다. 이를 통해 모든 .NET API의 고품질 API 설명서를 얻을 수 있습니다.
이를 위해 Xamarin 엔지니어링 팀과 협력하여 mdoc를 개발 및 사용하여 모든 .NET 참조 설명서를 생성했습니다.
MSDN 링크 - docs.microsoft.com으로 리디렉션
마이그레이션을 시작하면서 끊어진 링크가 없도록 하려 했습니다. 제품, 블로그 게시물, 기타 사이트에 통합될 수 있는 모든 MSDN 링크는 제대로 작동하고 표준 301 리디렉션을 통해 사용자를 새 위치로 안내해야 합니다.
커뮤니티 기여 가능
마이그레이션된 모든 콘텐츠는 이제 GitHub의 dotnet/dotnet-api-docs 리포지토리에 있는 오픈 소스입니다. 하지만 기여를 하기 위해 파일을 검색할 필요는 없습니다. .NET API 페이지로 이동하여 편집을 클릭하면 변경하려는 파일로 직접 이동됩니다.
