A docs.microsoft.com novemberi frissítése
A bejegyzést Jeff Sandquist, a Cloud + Enterprise részleg vezérigazgatója írta.
Ma büszkén jelenthetjük be, hogy migráltuk az Azure, a Visual Studio 2017 RC, a C++, a ASP.NET Core, az Entity Framework Core és az SQL dokumentációját Linuxon a docs.microsoft.com!
Azzal, hogy az összes tartalom egy helyen érhető el, ügyfeleink átlátható és egységes módon férhetnek hozzá a mobiltámogatáshoz, a honosításhoz, a megjegyzésekhez, a közösségi megosztáshoz vagy a közösségi közreműködéshez.
Noha a jelenlegi egy jelentős verzió, a tartalmat és a webhely funkcióit folyamatosan frissítjük, ezért várjuk a tartalommal kapcsolatos visszajelzéseit a UserVoice-on keresztül.
A következő hónapokban a jelenlegit új tartalommal bővítjük Dynamics 365, Windows Server, SQL Server, System Center és Windows asztali rendszer témákban.
- A Docs legfontosabb funkciói
- A Docs új funkciói
- Azure-dokumentáció
- Visual Studio 2017 RC-dokumentáció
- C++-dokumentáció
- ASP.NET Core-dokumentáció
- Entity Framework Core-dokumentáció
- Linux SQL-dokumentáció
Ha még járatos a docs.microsoft.com használatában, az alábbiakban megismerkedhet a legfontosabb új funkciókkal.
A bemeneten alapuló egyszerű fejlesztés egy cikk becsült olvasási idejét adja meg. Tudjuk, hogy sokan tanulják és értékelik a technológiákat az értekezletek közötti néhány perc alatt, és nagyobb valószínűséggel olvassa el a cikkeket, ha tudja, hogy mennyi időre van szükség.
Közöljük a tartalom közzétételének dátumát is, így ügyfeleink azzal is tisztában lehetnek, hogy mennyire frissek a cikkben szereplő információk, így nem kérdés többé, hogy mikor frissülhetett utoljára a cikk.
Annak érdekében, hogy a mobileszközökön, a táblagépeken és a PC-ken egyaránt azonos színvonalú szolgáltatást nyújthassunk, rugalmas elrendezést alakítottunk ki. Kis képernyős eszközökön az oldal tetején található Lehetőségek gombra kattintva ugyanazokat a lehetőségeket érheti el, mint amelyek az asztali böngészőkben is elérhetőek.
Nemzetközi felhasználóktól sok esetben kaptunk visszajelzést arról, mennyire fontos a honosított tartalom. A docs.microsoft.com immár 45 nyelvet támogat, köztük jobbról balra írt nyelveket, például az arabot és a hébert, valamint összesen 63 területi beállítást Dynamics 365-tartalmak esetén, és helyettesítő logikát alkalmaz, ha honosított tartalom nem érhető el. Ezzel a dokumentáció valóban globálissá vált, és készen áll az elkövetkezendő évben várható új tartalmak fogadására.
Kérdései, megjegyzései és visszajelzései fontosak a számunkra. A Livefyre-vel együttműködve minden cikkünkhöz megjegyzéseket és mellék megjegyzéseket fűztünk. Minden cikk tetején megjelenik egy lehetőség, amely közvetlenül a megjegyzések szakaszra ugrik.
Szívesen meghallgatjuk a véleményét, és a Docs oldalain megírt megjegyzéseket és kérdéseket figyelemmel kísérjük és válaszolunk rájuk.
Megjegyzés írásához bejelentkezhet Twitter-, Facebook-, Google-, Yahoo- vagy Microsoft-fiókjának hitelesítő adataival.
Ezen kívül követheti azt a hozzászólásláncot, ahol választ vár, így mindig értesülhet arról, ha egy munkatársunk vagy a közösség egy tagja válaszolt a kérdésére.
Széljegyzetet a cikkek minden bekezdéséhez és a külön kiemelt szövegrészekhez is készíthet. Ehhez jelöljön ki az egérmutatóval egy szövegrészletet, vagy kattintson a bekezdés jobb oldalán rámutatáskor megjelenő megjegyzés ikonra.
A lap tetején látható megosztás gombbal egyszerűen megoszthatja a tartalmat Twitter-követőivel vagy Facebook-barátaival.
Az egérrel kijelölt tartalmat a környezetfüggő vezérlő használatával is megoszthatja.
Egy témaválasztót is hozzáadtunk, hogy megváltozzon egy világos és egy sötét téma között, ami néhányuknak van [asked for on UserVoice](https://msdocs.uservoice.com/forums/364242-general-site-feedback/suggestions/14999211-komplete-dark-theme)
.
Ügyelünk a webes felhasználói környezettel kapcsolatos részletekre is: TechNet- és MSDN-felhasználóként már régóta bosszankodunk amiatt, hogy a cikkek URL-címei nem használhatók kényelmesen a böngészőkben. Íme egy példa erre a cikkre az új URL-címekkel.
https://technet.microsoft.com/library/dn646983.aspx3
https://docs.microsoft.com/intune/get-started/start-with-a-paid-subscription-to-microsoft-intune
Honlapunkon a cikkek túlnyomó többsége elő van készítve a közösségi közreműködésre. Ehhez kattintson a jobb felső menüsorban található Szerkesztés gombra, amely a vonatkozó GitHub-oldalra irányítja, ahol elágaztatást hozhat létre a tárházban, elvégezheti a változtatásokat, majd elküldheti a pull-kérelmet. Szívesen látjuk a honosított tartalmak szerkesztését és a közreműködéssel kapcsolatos általános tapasztalatokra vonatkozó visszajelzéseket is.
Noha számos funkció már a májusi indulás óta elérhető, sok új funkciót is bevezettünk, amelyeket az alábbiakban ismertetünk.
A tartalomjegyzéken azonnali hatású szűrő alkalmazható. Ez azt jelenti, hogy egyszerűen elkezdhet szöveget begépelni a megadott szöveget tartalmazó tartalom kereséséhez.
Ez a funkció a több oldalon is megjelenő tartalmak problémájára kínál megoldást. Az ASP.NET-alkalmazások Azure App Service-ben való üzembe helyezését bemutató cikk vajon az Azure vagy az ASP.NET alatt jelenjen meg? A legjobb, ha mindkét helyen, de a konzisztencia és a könnyű megtalálhatóság érdekében a tartalom mindkét szakaszban való duplikálása nélkül.
Ezért a tartalomkezelő csapatok a Docs bármely tartalmát kiválaszthatják, és az ügyfelek számára megjeleníthetik azt. Az alábbi ábrán egy olyan feltételezett elrendezés látható, amely Dockert használó .NET-fejlesztőknek szól, és amely az Azure, az ASP.NET, a .NET Core és a Visual Studio Azure SDK témakörök tartalmait is felhasználja – de mindez egyetlen egységes megjelenítéssel.
A dokumentációknál az egyik legbosszantóbb jelenség, amikor a bemutatott vagy hivatkozott kódminták nem működnek az olvasó gépén. A Microsoft több ezer kódmintát és kódrészlet tesz elérhetővé, és az a célunk, hogy az ügyfeleink biztosak lehessenek abban, hogy ezek valóban működőképesek a támogatott platformokon és konfigurációkkal.
Ezért kifejlesztettünk egy bővíthető folyamatos integrációs rendszert, amellyel biztosíthatjuk, hogy a minták lefordíthatók és az elvárásoknak megfelelően működnek meghatározott operációs rendszerek és eszközláncok mellett. Miközben igyekszünk még több csapatot bevonni a munkába, szeretnénk biztosítani, hogy a kódokat letöltő felhasználók biztosak legyenek abban, hogy a kód minden szükséges minőségellenőrzésen átesett.
Átalakítottuk a docs.microsoft.com alapjául szolgáló nyílt forráskódú DocFX-motort, és különféle platformokat és formátumokat támogató nyelvi kötéseket építettünk bele. Így támogatottak a következők:
- Azure CLI (Python)
- PowerShell
- .NET és .NET Core
- Java
- Swagger / REST API-k
Az ügyfelek számára ez azt jelenti, hogy a dokumentáció nem fog többé elcsúszni az API-k használata közben azok funkcióit tekintve, mivel most már csak egyetlen forrásra alapulnak mind a dokumentumok, mind pedig a kódok. Az API-referenciák támogatásáról további információt talál az alább található ASP.NET/EF szakaszokban.
A PDF-támogatás ugyancsak olyan fő funkció, amelyet számos ügyfelünk kért. A funkciónak köszönhetően letölthető egy adott dokumentumcsomag anélkül, hogy az több gigabájtnyi területet foglalna el, és egyszerűen másolható akár asztali gépen, akár mobileszközön.
A PDF-támogatást a tartalomjegyzéknél tettük elérhetővé. Gondoskodtunk róla, hogy az élő tartalom frissítésekor a PDF-fájl is frissüljön, így Ön mindig a legfrissebb és legkiválóbb tartalomhoz fér hozzá.
<img alt="screenshot16]()
Visszajelzését a tapasztalatokkal kapcsolatos töredezettségről és kihívásokról hallottuk, így már úton vagyunk az Azure-beli műszaki dokumentáció migrálásához a azure.microsoft.com, az MSDN-ről és a GitHubról , és konszolidáljuk azt a webhelyen https://docs.microsoft.com/azure/.
Megragadtuk a lehetőséget arra is, hogy módosítsuk az Azure témájú tartalmak kezdőlapjának megjelenését. Néhány fontosabb újdonság:
- A Szolgáltatások lapon az Azure-szolgáltatások kategóriák szerint csoportosítva szerepelnek.
- A Fejlesztő lapról érhető el az Azure-hoz kapcsolódó összes referenciatartalom a REST API, az Azure .NET SDK, az Azure Java SDK, az Azure CLI és az Azure PowerShell használatához.
- Az Architektúra lapon a rendszertervezők és a fejlesztők felhőléptékű tervezési mintákkal ismerkedhetnek meg.
A kezdőlapok egységes felépítésűek, és mindegyik tartalmazza a fontos erőforrásokra mutató alábbi hivatkozásokat:
- Áttekintés.
- A Bevezetés hivatkozással oktatóanyagok érhetők el az összes kapcsolódó platformhoz és programozási nyelvhez.
- Külön hivatkozás az adott szolgáltatáshoz kapcsolódó összes oktatóvideó eléréséhez.
- Hivatkozások az API-referenciatartalmakra.
- Egy hivatkozás segítségével a szolgáltatáshoz tartozó összes dokumentáció letölthető.
A docs.microsoft.com/azure webhelyre való átállás remek alkalmat kínált arra is, hogy egységesebbé tegyük a tartalomjegyzékkel történő navigációt. Bár mindegyik szolgáltatás egyedi jellegzetességekkel rendelkezik, már az egész webhelyen hasonló módon lehet navigálni.
Az Azure parancssori felülethez (CLI) kapcsolódó kódmintákban a jobb olvashatóság és könnyebb értelmezés érdekében színezéssel kiemeltük a kulcsszavakat és a paramétereket.
A felhasználók egyik leggyakoribb panasza az volt, hogy az API-kkal, a parancssori felülettel és a PowerShell-lel kapcsolatos tartalom általában nem naprakész. Ennek oka az volt, hogy a régebbi manuális munkafolyamataink nem tudtak lépést tartani az Azure gyors változásaival.
Az új kiadásban úgy módosítottuk rendszereinket, hogy közvetlenül a forráskódból hozzák létre a referenciát. Az új tartalmat így már az új buildek érkezésekor közzétesszük. Továbbá ahogyan felhasználóink eddig is közreműködhettek az útmutatók tartalmának szerkesztésében, ugyanezt a dokumentáció automatikusan generált részével is megtehetik majd.
Emellett a jövőben egységesen az Open API specifikációt (korábbi nevén Swagger) fogjuk használni REST API-k leírásához, így a REST-szolgáltatások kapcsán egységes adatreprezentáció lesz használható a dokumentációkhoz és az ügyféloldali SDK-khoz. A jövőben továbbá interaktív funkciókkal is bővíteni tudjuk majd a REST-dokumentációnkat, illetve a kérésekben/válaszokban szereplő hasznos adatok példáit.
A jelenlegi kiadással a következőkhöz biztosítunk támogatást:
- Azure CLI 2.0 (előzetes verzió)
- Azure PowerShell
- Azure Java SDK
- Azure .NET SDK
- Azure REST API-k
A Visual Studio valamennyi dokumentációját közvetlenül integráltuk a docs.microsoft.com új és megújult felületére.
A Visual Studio kezdőlap fontos hivatkozásokat kínál az első lépésekhez a Visual Studio 2017 kiadásra jelölt verziójával.
Innen érhető el többek között a telepítési útmutató, az újdonságok listája és a bevezetés a rendszer használatába. A honosított tartalom hamarosan elérhető lesz. Új tartalmakat teszünk elérhetővé különböző témák kapcsán, például az újrabontás, a projekten kívüli kódok kezelése, a teljesítményi problémák elhárítása, a Visual Studio indítási idejének optimalizálása, valamint a szerkesztőben elérhető új hatékonyságnövelő és kódban való navigálást segítő funkciók témakörében.
Most, hogy a Visual Studio már teljesen testreszabható módon, csak a kívánt összetevők használatával is telepíthető, arról is bővebb tájékoztatást nyújtunk, hogyan működik mindez a különböző fejlesztői projektek esetében, legyen szó ASP.NET-, Azure-, Python- vagy Windows-alapú feladatokról.
Emellett az ASP.NET Core és az Entity Framework Core dokumentációját is átemeltük a docs.asp.net, illetve a GitHub webhelyekről.
Mivel az ASP.NET Core és az Entity Framework Core nyílt forrású projektek, ezért mélyrehatóan integráltuk ezek forráskódját és három perjeles megjegyzéseit a megfelelő API-referenciadokumentumokba. Ez azt jelenti, hogy az API és a dokumentáció mindig automatikusan szinkronban marad.
Ügyfeleink régi kérésének eleget téve a C++-referenciaanyagokat kompaktabb formába ültettük át, a különböző témakörök között kevesebb hivatkozással. Az osztálytagok dokumentációja most már az adott osztállyal azonos témakörben érhető el.
Emellett bővebben tájékozódhat a C++-szabványoknak való megfeleléssel kapcsolatos legújabb változásokról és az új buildkészítési lehetőségekről (például /fastlink
), az új portolási útmutatóval frissítheti a Visual Studio korábbi verzióiból származó programkódokat, és megtudhatja, hogyan próbálhatja ki az új Linux-alapú fejlesztési képességet a gcc
segítségével!
A Linuxon futtatható SQL Server (az SQL Server vNext Customer Technical Preview 1 részeként) már elérhető és kipróbálható! A kezdőlapon elérhető fontos hivatkozások az első lépésektől kezdve ismertetik a Linuxon futó SQL Server kezelését és fejlesztési célú használatát. A honosított tartalom hamarosan elérhető lesz.
Arra törekszünk, hogy az új dokumentációs webhelyet még több szolgáltatással bővítsük, és a felhasználói élmény összhangban legyen termékeinkkel és szolgáltatásainkkal. Mivel Ön, a felhasználó a dokumentációs folyamat legkritikusabb része, javasoljuk, hogy lépjen kapcsolatba velünk, és küldjön visszajelzést arról, hogyan tehetjük jobbá ezt a felhasználói élményt a Twitteren.