Aankondiging van uniforme .NET-documentatie op docs.microsoft.com

Deze blogpost is geschreven door Jeff Sandquist, General Manager van het Azure Growth and Ecosystem-team.

Bijna een jaar geleden hebben we de .NET Core-referentiedocumentatie over docs.microsoft.com uitgetest. Vandaag kondigen we onze uniforme .NET API-referentie-ervaring aan. We begrijpen dat de productiviteit van ontwikkelaars essentieel is, van een hobbyontwikkelaar tot een startup, tot een onderneming. Met dat in gedachten hebben we nauw samengewerkt met het Xamarin-team om te standaardiseren hoe we .NET API's bij Microsoft documenteren, ontdekken en navigeren.

Alle .NET-documentatie - op één plek

Eerder, als je een . NET-SDK die door Microsoft is verzonden, moest u enige tijd doorbrengen met uw favoriete zoekmachine, proberen om zowel de plaats te vinden waar u deze kunt downloaden, als de relevante API-documentatie te ontdekken.

We zijn van plan om alles te hebben. NET-compatibele SDK's geïntegreerd en doorzoekbaar op één plaats: https://docs.microsoft.com/dotnet/api. Daar vindt u referentiedocumentatie voor .NET Framework, .NET Core, .NET Standard en Xamarin, evenals documentatie voor onze Azure NuGet-pakketten. In de komende maanden voegen we meer SDK's toe aan deze ervaring.

Inleiding tot de API-browser

Ons belangrijkste doel is om een IntelliSense-achtige ervaring te bieden om in alle .NET API's vanuit een webbrowser te zoeken. U kunt zoeken naar een naamruimte, klasse, methode of interface door de volledige of gedeeltelijke naam rechtstreeks op de PAGINA API-browser te typen.

API-browser

Als u niet zeker weet tot welke SDK een specifiek type, lid of naamruimte behoort, kunt u eenvoudig alle API's selecteren in de vervolgkeuzelijst api-bereik en zoeken in alle beschikbare referentiedocumenten. Als u uw zoekopdracht wilt beperken, kunt u ook een specifiek framework of sdk en de bijbehorende versie selecteren, bijvoorbeeld .NET Framework 4.7 en alleen zoeken binnen die set API's.

De API Browser-ervaring is ook geïntegreerd boven aan de inhoudsopgave voor . MET NET-API's kunt u snel elke API vinden, ongeacht waar u zich in de referentiedocumentatie bevindt:

API-browser op pagina

Zodra u zich in een specifieke naamruimte bevindt, is de API-browser alleen gericht op de familie van API's die met elkaar zijn verbonden, zodat uw zoekopdracht altijd de best mogelijke resultaten retourneert op basis van uw context.

Ondersteuning voor versiebeheer

U hoeft zich niet meer af te vragen of een type leden beschikbaar heeft in een specifieke versie van .NET Framework of het Azure Storage NuGet-pakket. U hoeft alleen de versie te wijzigen van het API-browserbesturingselement en de inhoud wordt dienovereenkomstig aangepast:

Verwijzings-toc

Gebouwd met Open Source in gedachten

Voor het bouwen van de API-browser hebben we open standaarden en hulpprogramma's gebruikt. In de kern hebben we DocFX gebruikt: de open hulpprogrammaketen voor het genereren van documentatie, samen met de mdoc-toepassing van Xamarin.

Al onze beheerde referentiedocumentatie is nu automatisch gegenereerd op basis van binaire bestanden die worden verzonden op NuGet of deel uitmaken van de belangrijkste frameworkdistributies, zoals .NET Framework of .NET Core.

Onze infrastructuur voor continue integratie stelt ons in staat om nauwkeurige documentatie te hebben voor de nieuwste API's die nu binnen enkele uren na de release openbaar kunnen zijn, open voor bijdragen. We hebben ook alle .NET API-documentatie over de ECMAXML-indeling gestandaardiseerde, waarmee een consistente en uitgebreide API-weergave wordt gemaakt, ongeacht de SDK die wordt gedocumenteerd. Bovendien hoeft u de complexiteit van de bestandsindeling niet te kennen, omdat u inhoud kunt bijdragen in Markdown, ingesloten in automatisch gegenereerde documenten. Communitybijdragen voor referentiedocumentatie worden binnen de volgende maand ingeschakeld.

Focus op inhoud

Naast de nieuwe ervaringen hebben we ook de referentie-inhoud geoptimaliseerd om beter vindbaar en leesbaarder te zijn. We hebben de inhoudsopgave bijgewerkt zodat deze altijd gericht is op een naamruimte. Of u nu bladert naar informatie over een naamruimte, type of lid, we laten u altijd alleen de bovenliggende naamruimte zien met alle onderliggende & typen hun respectieve gegroepeerde leden:

Verwijzings-toc

Dit betekent dat referentiepagina's overzichtelijk zijn en u eerst de belangrijkste informatie laten zien, zoals algemene overzichten en voorbeelden, allemaal in één oogopslag.

U ziet ook voorbeelden die vanaf het begin relevant voor u zijn, gefilterd op uw programmeertaal van keuze. U hoeft niet langer naar de onderkant van de pagina te schuiven om deze te vinden.

Feedbackgestuurd

Dit is slechts het begin van het vernieuwen van de referentiedocumentatie-ervaring. We willen uw feedback horen over hoe we onze documentatie aantrekkelijker, nuttiger kunnen maken en u zo snel mogelijk op weg helpen. Ga naar onze UserVoice-site en laat ons weten hoe we onze API Browser-ervaring kunnen verbeteren. U kunt ook altijd contact met ons opnemen via Twitter, @docsmsft, voor snelle updates.