docs.microsoft.com 的 11 月更新
本文作者:Jeff Sandquist,Cloud + Enterprise 部总经理。
今天,我们非常自豪地宣布我们已将 Linux 上的 Azure、Visual Studio 2017 RC、C++、ASP.NET Core、Entity Framework Core 和 SQL 相关文档迁移到了 docs.microsoft.com!
汇总所有内容能够推动客户在移动设备支持、本地化、评论、社交分享和社区贡献方面的一致性体验。
虽然这是很重要的版本,但是我们会继续定期更新内容和站点功能,因此,请确保就内容体验向我们发送 UserVoice 反馈。
在接下来的几个月里,你还可以期待 Dynamics 365、Windows Server、SQL Server、System Center 和 Windows 桌面的新增内容。
- Docs 主要功能
- 新的 Docs 功能
- Azure 文档
- Visual Studio 2017 RC 文档
- C++ 文档
- ASP.NET Core 文档
- Entity Framework Core 文档
- Linux 上的 SQL 文档
对于不熟悉 docs.microsoft.com 用户,以下提供了具有全新体验的部分主要功能。
根据你们的意见,我们完成了一项简单的功能提升,那就是提供文章的估计阅读时间。 我们知道大多数人在会议之间的那几分钟时间了解和评估技术,如果你知道需要花费多少时间,就更有意愿阅读文章。
我们还为内容添加了时间戳,帮助客户了解内容的新鲜程度 - 无需再猜测文章的上次更新时间。
为了能够在移动设备、平板电脑和 PC 上提供卓越的体验,我们实施了响应式布局。 单击小屏幕设备页面顶部的“选项” 按钮可以访问在桌面浏览器中看到的相同选项。
我们总是听见国际客户谈及本地化内容的重要性。 docs.microsoft.com 现在支持 45 种语言,包括从右到左书写的语言(如阿拉伯语和希伯来语),并且支持总共 63 个区域设置,在本地化文档可能无法获得时,使用回退逻辑处理 Dynamics 365 内容。 这使 docs 真正地全球通用,而且可以在新的一年添加其他内容。
你们的问题、意见和反馈对我们至关重要。 我们已经与 Livefyre 合作,可以在我们的所有文章上添加评论和旁注。 在每篇文章的顶部,可以看到直接跳转到评论部分的选项。
我们希望收到你的反馈并且正在努力关注和回复 Docs 页左侧的所有评论和问题。
若要评论,可以使用现有的 Twitter、Facebook、Google、Yahoo 或 Microsoft 凭据登录。
此外,还能够跟踪想要跟进的线程 - 我们团队成员或社区成员回复你时,你能始终获悉动态。
此外还可以在每个内容段落或专门突出显示的文本上添加旁注。 为此,只需用鼠标光标选择文本块,或单击评论图标(评论图标显示在悬停段落的右侧)。
通过页面顶部的共享按钮可以轻松地将内容与 Twitter 关注者和 Facebook 好友进行共享。
此外可以使用鼠标直接选择内容,并通过上下文小组件共享。
我们还添加了一个主题选取器,以便你可以在浅色和深色主题之间更改,这是你们中的一些人拥有 [asked for on UserVoice](https://msdocs.uservoice.com/forums/364242-general-site-feedback/suggestions/14999211-komplete-dark-theme)
的。
我们很关心 Web 体验,但是作为 TechNet 和 MSDN 的用户,经常困扰我们的一件事情是文章的 URL 不友好,也不易读。 下面示例为使用新 URL 的同一篇文章。
https://technet.microsoft.com/library/dn646983.aspx3
https://docs.microsoft.com/intune/get-started/start-with-a-paid-subscription-to-microsoft-intune
已对贡献社区启用了站点上的绝大多数文档。 只需单击菜单右上方的“编辑”按钮,即可转到相应的 GitHub 页面,分叉存储库,做出更改,然后提交你的拉取请求。 我们欢迎对本地化内容进行编辑,也欢迎对贡献的整体体验提供反馈!
自 5 月份产品发布日以来已发布了很多功能,但我们还是增加了大量的新功能,如下所述。
我们已经让目录可以即时筛选。 这意味着你只需键入几个字符,即可筛选任何匹配的文本,从而找出正在寻找的内容。
我们添加的另一个关键功能解决了多个站点上的内容的问题。 有关将 ASP.NET 应用部署到 Azure App Service 的文章应列在 Azure 下还是列在 ASP.NET 下? 答案是都可以,但为了易于发现和保持一致,不会复制这两个站点上的内容。
为此,我们使内容团队可以选择文档上的任何内容,然后为客户创建该内容的视图。 下图显示了对于使用 Docker(其可能包含来自 Azure、ASP.NET、.NET Core 和 Visual Studio Azure SDK 团队的内容)的 .NET 开发人员来说,设想布局的样子 - 所有内容都在单个视图中。
文档最令人头疼的特点之一就是演示或链接的示例不能在计算机上工作。 在 Microsoft 中,我们有数千个代码示例和代码片段,并且我们希望确保客户相信这些样本能够在受支持的平台和配置上工作。
为此,我们开发了一个可扩展的持续集成 (CI) 系统,以确保这些示例为给定的操作系统和工具链编译并生成预期输出。 我们正努力为此投入更多的团队的同时,希望确保下载代码的用户确信它通过了所有必要的质量检查。
我们已重新设计了基础 DocFX 引擎(为 docs.microsoft.com 提供支持的开源组件),从而为不同的平台和格式包括语言绑定。 这包括对以下内容的支持:
- Azure CLI (Python)
- PowerShell
- .NET 和.NET Core
- Java
- Swagger/REST API
对客户而言,这意味着文档不会再与 API 功能失去同步,因为现在有一个驱动文档和代码的真实原样。 可以在下面的 Azure 和 ASP.NET/EF 部分阅读有关 API 引用的特定支持的详细信息。
客户要求的另一个主要功能是 PDF 支持 - 可以下载一组特定的文档而不会占用大量存储空间,并且无论是在桌面还是移动设备上,都可以随身携带到任何地方。
为了实现此功能,我们为目录启用了 PDF 支持。 在实时站点上更新内容时,我们确保 PDF 文件已更新,以便你能始终获取最新和最好的内容。
<img alt="screenshot16]()
我们收到过有关体验比较分散和困难的反馈,因此我们正在努力将 Azure 技术文档从 azure.microsoft.com、MSDN 和 GitHub 迁移出来,并合并到 https://docs.microsoft.com/azure/ 中。
我们也尝试着改变 Azure 内容登录页的外观和视觉感受。 部分关键亮点包括:
- “服务”选项卡按类别分组列出 Azure 服务。
- “开发人员”选项卡列出 REST APIAzure.NET SDK、Azure Java SDK、Azure CLI 和 Azure PowerShell 的所有 Azure 参考内容。
- “体系结构”选项卡让设计师和开发人员了解云级别设计模式。
我们已确保登陆页面保持一致,关键资源链接包括:
- “服务概述”链接。
- 用于所有相关平台和编程语言的“入门”教程。
- 指向给定服务的所有视频教程的链接。
- API 参考内容的链接。
- 用于下载该服务的所有文档的链接。
正值转移到 docs.microsoft.com/azure 之际,我们利用这个机会提高了目录导航的一致性。 虽然每个服务各具特色,但现在你在站点中看到的导航都大同小异。
有关表示 Azure 命令行接口 (CLI) 的代码示例,我们为关键字和参数添加了彩色,方便你阅读和理解代码。
大家反馈的最大难题之一是我们的 API、命令行和 PowerShell 内容永远不会更新。 只要发生 Azure 更改,我们以前的手动工作流就不再工作。
针对此版本,我们已将系统更改为直接从源代码创建引用。 发布新的内部版本时,也将同时发布新内容。 正如你能对“工作方式”内容做出贡献一样,你也同样能对文档的自动生成部分做出贡献。
我们还对开放 API 规范(以前称为 Swagger)的使用实现标准化以描述我们的 REST API,这将为用于文档和客户端 SDK 的 REST 服务提供一致的数据表示形式。 将来我们还能够将交互式功能添加到 REST 文档和示例请求/响应有效负载中。
在此版本中我们已启用:
我们引入了所有 Visual Studio 文档,直接融入更新的 docs.microsoft.com 体验中。
Visual Studio 中心页包含指向 Visual Studio 2017 候选发布版本入门的重要链接。
其中包括安装指南、新增功能和入门教程。 本地化内容即将推出。 将对一些主题(如重构、使用不在同一项目中的代码、调试性能问题、优化 Visual Studio 启动时间的提示、编辑器中所有新的工作效率和代码导航功能等)提供新内容。
现在,Visual Studio 支持完全自定义安装过程,在此过程中你只会获得需要使用的组件,你可以详细了解这些组件如何适用于单独的开发项目,而无需考虑你的工作负载是否涉及 ASP.NET、Azure、Python 或 Windows 平台。
ASP.NET Core 和 Entity Framework Core 文档也已分别从 docs.asp.net 和 GitHub 中迁移出来。
由于 ASP.NET Core 和 Entity Framework Core 都是开源项目,我们已经深入地集成其源代码和三斜杠注释,以生成相应的 API 参考文档。 这意味着 API 和文档将始终自动保持同步。
为响应客户长期以来的请求,我们已将 C++ 引用重构为更紧凑且需要更少主题间链接的格式。 现在,在与类相同的主题中,可以找到类成员的所有文档。
此外,了解最新 C++ 标准一致性更改和新的构建选项(如 /fastlink
)的详细信息,使用新的移植指南从以前的 Visual Studio 版本中升级代码,并了解如何尝试新的支持以使用 gcc
在 Linux 系统上进行构建!
此处是 Linux 上的 SQL Server(SQL Server vNext 客户技术预览版 1 的一部分),可供你试用! 中心页包括从入门到使用 Linux 上的 SQL Server 进行管理和开发的重要链接。 本地化内容即将推出。
我们很希望将更多的功能带到新的文档站点中,并确保体验与我们的产品和服务保持一致。 由于你(用户)是文档过程中最重要的部分,因此我们鼓励你与我们联系,并就我们如何在 Twitter 上改进此体验提供反馈。