Listopadová aktualizace pro docs.microsoft.com
Autorem tohoto článku je Jeff Sandquist, šéf oddělení Cloud + Enterprise.
Dnes s hrdostí oznamujeme, že jsme migrovali dokumentaci pro Azure, Visual Studio 2017 RC, C++, ASP.NET Core, Entity Framework Core a SQL v Linuxu do docs.microsoft.com!
Tím, že jsme shromáždili veškerý obsah na jednom místě, jsme pro naše zákazníky vytvořili konzistentní prostředí pro mobilní podporu, lokalizaci, komentáře, sdílení v sociálních sítích a příspěvky komunity.
Tím to ale nekončí. Dál budeme pravidelně aktualizovat obsah a funkce webu, proto nám nezapomeňte poslat své názory přes UserVoice, abychom věděli, jak se vám s naší dokumentací pracuje.
Během následujících měsíců se také můžete těšit na další obsah pro Dynamics 365, Windows Server, SQL Server, System Center a Windows Desktop.
- Klíčové funkce Dokumentace
- Nové funkce Dokumentace
- Dokumentace k Azure
- Dokumentace k sadě Visual Studio 2017 RC
- Dokumentace k C++
- Dokumentace k ASP.NET Core
- Dokumentace k Entity Framework Core
- Dokumentace k SQL on Linux
Pro ty z vás, kteří s webem docs.microsoft.com zatím nemáte zkušenosti, uvádíme pár klíčových funkcí našeho nového prostředí.
Jednoduchým vylepšením, které jsme na základě vašich vstupů udělali, je poskytnout odhadovanou dobu čtení článku. Víme, že mnozí z vás se během těchto několika minut mezi schůzkami učí a vyhodnocují technologie. Pokud víte, kolik času je potřeba, přečtete si články s větší pravděpodobností.
Ke každému článku jsme přidali časový údaj, abyste věděli, jak jsou informace staré, a nemuseli odhadovat, kdy byl článek naposledy aktualizován.
Kvůli zajištění optimálního uživatelského prostředí na mobilních zařízeních, tabletech i počítačích jsme přešli na přizpůsobivé rozložení. Když na zařízení s malou obrazovkou klepnete v horní části stránky na tlačítko Možnosti, zobrazí se stejné možnosti jako v prohlížeči na počítači.
Od zákazníků v různých zemích často slýcháme, jak je pro ně lokalizovaný obsah důležitý. Web docs.microsoft.com nyní podporuje 45 jazyků, včetně jazyků psaných zprava doleva, jako je arabština nebo hebrejština, a také celkem 63 národních prostředí pro obsah Dynamics 365 s náhradní logikou pro případ, že lokalizované dokumenty nejsou k dispozici. Díky tomu je dokumentace skutečně globální a připravená na další obsah, který přidáme v novém roce.
Vaše dotazy, komentáře a názory jsou pro nás důležité. Ve spolupráci se společností Livefyre poskytujeme komentáře a poznámky ke všem našim článkům. V horní části každého článku uvidíte možnost přejít přímo na oddíl komentáře.
Chceme znát váš názor. Všechny komentáře a dotazy přidané na stránky Dokumentace budeme monitorovat a odpovídat na ně.
Pokud chcete přidat komentář, můžete se přihlásit pomocí přihlašovacích údajů svého účtu Twitter, Facebook, Google, Yahoo nebo Microsoft.
Kromě toho budete moct sledovat vlákna diskuzí, které vás zajímají. Hned se dozvíte, když náš specialista nebo člen komunity zareaguje na váš příspěvek.
K jednotlivým odstavcům obsahu nebo ke konkrétnímu zvýrazněnému textu můžete také přidávat poznámky na okraj. Stačí kurzorem myši vybrat blok textu nebo kliknout na ikonu komentáře, která se zobrazí na pravé straně odstavce, když na něj přejdete myší.
Tlačítko pro sdílení v horní části stránky umožňuje snadno sdílet obsah na Twitteru nebo Facebooku.
Obsah můžete také přímo vybrat myší a sdílet ho prostřednictvím kontextově závislého widgetu.
Přidali jsme také výběr motivu, abyste mohli přepínat mezi světlým a tmavým motivem, něco, co někteří z vás mají [asked for on UserVoice](https://msdocs.uservoice.com/forums/364242-general-site-feedback/suggestions/14999211-komplete-dark-theme)
.
Uživatelské prostředí na našich stránkách je pro nás velice důležité a jednou z věcí, které nás jako uživatele TechNetu a MSDN dlouho trápily, bylo, že jednotlivé články neměly popisné a čitelné adresy URL. Tady je příklad stejného článku s našimi novými adresami URL.
https://technet.microsoft.com/library/dn646983.aspx3
https://docs.microsoft.com/intune/get-started/start-with-a-paid-subscription-to-microsoft-intune
Většina článků dokumentace na našem webu umožňuje členům komunity přidávat příspěvky. Když v pravé horní nabídce kliknete na tlačítko Upravit, přejdete na příslušnou stránku GitHubu a potom na rozvětvení úložiště. Pak můžete provést změnu a odeslat žádost o stažení. Uvítáme úpravy lokalizovaného obsahu a jakoukoli zpětnou vazbu ohledně vašeho používání prostředí pro příspěvky.
Celou řadu funkcí už možná znáte od jejich spuštění v květnu. Přidali jsme ale i pár nových – podívejte se níže na jejich seznam.
Obsah můžete okamžitě filtrovat. To znamená, že stačí zadat prvních pár znaků a začne se filtrovat odpovídající text. Takže rychle najdete, co hledáte.
Další důležitá funkce, kterou jsme přidali, řeší problém se stejným obsahem na více stránkách. Měl by být článek o nasazení aplikace ASP.NET do Azure App Service uvedený v části Azure nebo v části ASP.NET? Pochopitelně v obou. Zároveň by se ale neměl duplikovat, aby jeho obsah zůstal konzistentní a nedocházelo k problémům při vyhledávání.
Našemu týmu, který se stará o vytváření obsahu, jsme proto umožnili vybrat libovolný článek a vytvořit jeho náhledové zobrazení pro zákazníky. Na obrázku níže vidíte, jak může například vypadat rozložení pro vývojáře v .NET v Dockeru, kteří využívají obsah od týmů Azure, ASP.NET, .NET Core a Visual Studio Azure SDK – všechno v jediném zobrazení.
Může být frustrující, když se při používání dokumentace pokoušíte aplikovat ukázku kódu na svém počítači, ale nedostaví se očekávaný výsledek. Naši specialisté vytvořili tisíce ukázek a fragmentů kódu a u všech klademe důraz na to, aby se mohli zákazníci spolehnout, že budou tyto ukázky fungovat v příslušné platformě a konfiguraci.
Proto jsme vyvinuli rozšiřitelný systém kontinuální integrace (CI), abychom zajistili, že se ukázka pro danou skupinu operačních systémů a sad nástrojů správně zkompiluje a vytvoří očekávaný výstup. Pokračujeme v zapojování dalších týmů a dbáme na to, aby náš kód, který si uživatelé stáhnou, prošel všemi nezbytnými kontrolami kvality.
Přepracovali jsme základní modul DocFX, Open Source součást, na které běží web docs.microsoft.com, a přidali sady jazyků pro různé platformy a formáty. Teď obsahuje podporu pro:
- Azure CLI (Python)
- PowerShell
- .NET a .NET Core
- Java
- Swagger / REST API
Z toho vyplývá, že kód v dokumentaci už by se neměl odchýlit od reálného fungování rozhraní API, protože dokumentace i samotný kód teď vycházejí ze stejného zdroje. Informace o podpoře pro konkrétní rozhraní API najdete níže v částech Azure a ASP.NET/EF.
Další významnou funkcí, o kterou nás zákazníci žádali, je podpora PDF. Můžete si stáhnout celou skupinu článků, aniž by vám zabraly několik GB místa na disku, a budete je mít přístupné kdekoli, jak na počítači, tak v mobilním zařízení.
Za tímto účelem jsme pro články dokumentace aktivovali podporu PDF. Soubory PDF se aktualizují, jakmile se aktualizuje obsah na živém webu, takže máte k dispozici vždy přesné a aktuální informace.
<img alt="screenshot16]()
Slyšeli jsme vaši zpětnou vazbu ohledně fragmentace a problémů s prostředím, takže jsme na dobré cestě k migraci technické dokumentace Azure z azure.microsoft.com, MSDN a GitHubu a konsolidaci na https://docs.microsoft.com/azure/.
Také jsme využili této příležitosti k tomu, abychom změnili vzhled cílové stránky pro obsah Azure. Mezi hlavní vylepšení patří:
- Karta Services (Služby), kde najdete výčet služeb Azure seskupených podle kategorií.
- Karta Developer (Vývojář), na které najdete veškerý referenční obsah Azure pro REST API, Azure .NET SDK, Azure Java SDK, Azure CLI a Azure PowerShell.
- Karta Architecture (Architektura) pro architekty a vývojáře, kde najdete vzory návrhu škálování cloudu.
Zajistili jsme, aby naše cílové stránky byly konzistentní a odkazovaly na nejdůležitější materiály, včetně následujících:
- Odkaz na přehled služeb
- Kurzy Začínáme pro všechny odpovídající platformy a programovací jazyky
- Odkaz na všechny videokurzy pro jednotlivé služby
- Odkazy na referenční obsah rozhraní API
- Odkaz na stažení všech článků pro danou službu
V rámci přesunu na web docs.microsoft.com/azure jsme také zlepšili konzistenci navigace v obsahu. Každá služba má jedinečné vlastnosti, proto se vám teď při procházení webu zobrazí podobná navigace.
Do ukázek kódu rozhraní příkazového řádku Azure (CLI) jsme přidali zabarvení klíčových slov a parametrů, takže je kód čitelnější a přehlednější.
Jedním z největších problémů, který trápil všechny naše zákazníky, byla neaktuálnost dokumentace k rozhraní API, příkazovému řádku a prostředí PowerShell. Předchozí pracovní postupy vytváření referenčních materiálů nestačil tempu probíhajících změn v Azure.
Proto jsme naše systémy změnili tak, aby se referenční materiály vytvářely přímo ze zdrojového kódu. Při doručení nového sestavení je doručen i nový obsah. A stejně jako můžete přispívat do našeho obsahu How To (Postupy), budete moct přispívat i do automaticky generované části dokumentace.
Také jsme standardizovali používání specifikací Open API Specification (dříve známých jako Swagger), kde popisujeme naše REST API. Výsledkem je konzistentní znázornění dat pro služby REST, které je možné použít pro dokumentaci, stejně jako klientských sad SDK. V budoucnu také přidáme do dokumentace k REST interaktivní funkce a příklady datových částí požadavků a odpovědí.
V rámci této aktualizace jsme povolili:
- Azure CLI 2.0 (Preview)
- Azure PowerShell
- Azure Java SDK
- Azure .NET SDK
- Rozhraní REST API platformy Azure
Zavádíme úplně novou dokumentaci k sadě Visual Studio, která je integrovaná přímo do nového, aktualizovaného prostředí docs.microsoft.com.
Stránka centra sady Visual Studio obsahuje základní odkazy na úvod k verzi Release Candidate sady Visual Studio 2017.
Jsou to například kurzy Průvodce instalací, Co je nového a Začínáme. Už brzy bude k dispozici i lokalizovaný obsah. Nový obsah bude k dispozici pro témata, jako je refaktoring, práce s kódem, který není v projektu, ladění problémů s výkonem, tipy pro optimalizaci doby spuštění sady Visual Studio nebo podrobnosti o všech nových funkcích produktivity a navigace v kódu v editoru a další.
Teď, když Visual Studio podporuje zcela přizpůsobitelný proces instalace, při kterém si nastavíte jenom požadované komponenty, můžete si přečíst o tom, jak to může fungovat pro jednotlivé vývojové projekty, bez ohledu na to, jestli vaše pracovní postupy zahrnují platformu ASP.NET, Azure, Python nebo Windows.
Migrovali jsme dokumentaci k ASP.NET Core z docs.asp.net a dokumentaci k Entity Framework Core z GitHubu.
Protože ASP.NET Core a Entity Framework Core jsou Open Source projekty, integrovali jsme jejich zdrojový kód včetně komentářů za třemi lomítky do sestavování příslušných referenčních materiálů k rozhraním API. Jinými slovy, rozhraní API a dokumentace teď budou vždy automaticky synchronizované.
V reakci na opakované žádosti zákazníků jsme refaktorovali referenční materiály k C++ do kompaktnějšího formátu, ve kterém je méně vzájemného odkazování mezi jednotlivými tématy. Nyní najdete veškerou dokumentaci ke členům třídy ve stejném tématu jako třídu samotnou.
Kromě toho si můžete projít další informace o nejnovějších změnách v dodržování standardů C++ a nových možnostech sestavení, jako je /fastlink
, použít nové pokyny pro přenos, které vám pomůžou upgradovat z kódu předchozí verze sady Visual Studio, a dozvědět se, jak můžete vyzkoušet novou podporu pro sestavování v systémech Linux pomocí gcc
.
SQL Server on Linux (součást serveru SQL Server vNext Customer Technical Preview 1) je na světě a připraven k vyzkoušení. Stránka centra obsahuje klíčové odkazy, které vás provedou od úplných základů až po správu a vývoj v SQL Serveru on Linux. Brzy bude k dispozici i lokalizovaný obsah.
Neustále se na nový web dokumentace snažíme doplňovat další a další funkce a udržovat jeho prostředí konzistentní s našimi produkty a službami. Vzhledem k tomu, že vy, uživatel, jste nejdůležitějším dílem v procesu dokumentace, doporučujeme, abyste se s námi na Twitteru ozvěli a poskytli nám zpětnou vazbu o tom, jak pro vás můžeme toto prostředí vylepšit.