docs.microsoft.com의 통합 .NET 참조 환경 발표

이 게시물은 Azure Growth and Ecosystem(성장 및 에코시스템) 팀의 총괄 관리자인 Jeff Sandquist에 의해 작성되었습니다.

거의 1년 전 Microsoft는 docs.microsoft.com에서 .NET Core 참조 설명서를 시험 운영했습니다. 오늘 통합 .NET API 참조 환경을 발표하게 되어 기쁘게 생각합니다. Microsoft는 취미로 하는 개발자부터 신생 기업, 엔터프라이즈에 이르기까지 개발자의 생산성이 핵심이라는 점을 잘 알고 있습니다. 이러한 사실을 염두에 두고 Microsoft는 Xamarin 팀과 긴밀하게 제휴하여 Microsoft에서 .NET API를 문서화, 검색 및 탐색하는 방법을 표준화했습니다.

모든 .NET 설명서가 한곳에

이전에는 Microsoft에서 제공하는 .NET 기반 SDK를 찾으려는 경우 선호하는 검색 엔진으로 검색하는 데 시간을 들여 해당 SDK를 다운로드할 수 있는 위치와 관련 API 설명서를 검색할 수 있는 위치를 모두 찾아야 했습니다.

앞으로는 https://docs.microsoft.com/dotnet/api 한곳에서 모든 .NET 호환 SDK를 통합하여 검색할 수 있도록 할 계획입니다. 거기서 .NET Framework, .NET Core, .NET 표준 및 Xamarin에 대한 참조 설명서뿐만 아니라 Azure NuGet 패키지에 대한 설명서도 찾을 수 있습니다. 앞으로 몇 달 동안 이 환경에 더 많은 SDK를 추가할 것입니다.

API 브라우저 소개

주요 목표는 웹 브라우저에서 모든 .NET API를 검색할 수 있는 IntelliSense와 유사한 환경을 구축하는 것입니다. API 브라우저 페이지에서 직접 이름 전체 또는 일부를 입력하여 네임스페이스, 클래스, 메서드 또는 인터페이스를 검색할 수 있습니다.

특정 형식, 멤버 또는 네임스페이스가 속한 SDK를 잘 모르는 경우 API 범위 드롭다운에서 모든 API를 선택하고 사용 가능한 모든 참조 설명서에서 검색하면 됩니다. 또는 검색을 제한하려는 경우 특정 프레임워크 또는 SDK 및 해당 버전(예: .NET Framework 4.7)을 선택하고 해당 API 집합 내에서만 검색할 수 있습니다.

또한 API 브라우저 환경은 .NET 기반 API 목차의 맨 위에 통합되어 있어 어떤 참조 설명서 내에 있든 관계없이 API를 빠르게 찾을 수 있습니다.

특정 네임스페이스에 있는 경우 API 브라우저 범위가 함께 연결된 API 집합으로만 지정되어 검색에서는 컨텍스트에 따라 항상 가능한 최상의 결과를 반환합니다.

버전 관리 지원

더 이상 형식이 특정 버전의 .NET Framework 또는 Azure Storage NuGet 패키지에서 사용할 수 있는 멤버를 포함하고 있는지를 궁금해할 필요가 없습니다. API 브라우저 컨트롤에서 버전만 변경하면 콘텐츠가 적절하게 조정됩니다.

오픈 소스를 기반으로 빌드됨

API 브라우저를 빌드하는 데 개방형 표준 및 도구를 사용했습니다. 그 중심에는 개방형 설명서 생성 도구 체인인 DocFX와 함께 Xamarin의 mdoc 애플리케이션을 활용했습니다.

모든 관리되는 참조 설명서는 이제 NuGet에서 제공되거나 기본 프레임워크 배포(예: .NET Framework 또는 .NET Core)의 일부인 바이너리에서 자동 생성됩니다.

연속 통합 인프라를 통해 이제 릴리스로부터 몇 시간 내에 기여를 위해 개방형으로 공개될 수 있는 최신 API에 대한 정확한 설명서를 가질 수 있습니다. 또한 문서화되는 SDK와 관계없이 일관되고 포괄적인 API 표현을 만드는 ECMAXML 형식으로 모든 .NET API 설명서를 표준화했습니다. 또한 자동 생성된 설명서에 포함된 Markdown으로 콘텐츠를 기여할 수 있으므로 파일 형식의 복잡성을 알 필요가 없습니다. 참조 설명서의 커뮤니티 기여는 다음 달 안에 사용할 수 있습니다.

콘텐츠에 집중

새로운 환경 외에 검색 가능성과 가독성을 높이기 위해 참조 콘텐츠도 최적화했습니다. 항상 네임스페이스 중심이 되도록 목차를 업데이트했습니다. 네임스페이스, 형식 또는 멤버 중 어느 것에 대한 정보를 검색하든 항상 모든 해당 하위 자식 유형 및 해당 그룹화된 멤버와 함께 부모 네임스페이스를 보여 줍니다.

즉, 참조 페이지에는 불필요한 내용 없이 일반 개요 및 예제와 같은 가장 중요한 정보가 먼저 표시되며, 모두 한눈에 볼 수 있습니다.

원하는 프로그래밍 언어로 필터링되어 시작부터 관련된 예제를 살펴볼 수도 있습니다. 더 이상 해당 예제를 찾기 위해 페이지 맨 아래까지 스크롤할 필요가 없습니다.

사용자 의견 기반

이는 참조 설명서 환경 개선을 위한 시작에 불과합니다. 설명서를 더 매력적이고 유용하게 하고 최대한 빨리 필요한 내용을 찾을 수 있게 하는 방법에 대한 의견을 들려주시기 바랍니다. UserVoice 사이트로 이동하여 API 브라우저 환경을 개선할 수 있는 방법을 알려주세요. 또한 Twitter @docsmsft를 통해서도 업데이트 내용을 신속하게 알아볼 수 있습니다.