最近，社区成员Abdelhadi Bukres提醒了我保持良好沟通的必要性。他正确地指出，距离我上次更新DNN文档项目的状态已经太久了。我们经常陷入项目和日常任务的杂草中，忘记了时间已经过去了多少。
为了避免你认为DNN Docs项目因为我没有写博客而濒临死亡，让我尽快纠正这个想法:)自项目开始以来，我们每周都开会，并努力推动项目向前发展。
正如我在前一篇文章中试图解释的那样，成功的帮助项目有无数的成分。除了内容之外，还有一些技术方面的问题，如工具、托管、构建工具、版本控制等。当然，我们需要考虑使用文档的不同类型的用户——他们的意图是什么，以及如何组织他们的旅程，以便他们能够有效地实现他们的目标。同样重要的是，我们需要创建一个系统，欢迎来自社区的贡献，同时保持对最终用户的共同声音和一致的呈现。不用说，这是一个艰巨的任务。
过去几周我疏忽了分享我们的进展，所以我想继续我的什么是好的文档发表一篇文章，看看我们为文档项目确定的功能集，以及这个列表所提示的一些决定。
请注意，我们并没有单独创建它。除了分析多个文档项目之外，我们还从社区征求并收到了建议和反馈。我还需要注意的是，该列表并非详尽无遗，也不会将列表中的所有内容都纳入项目中，有些内容可能会在项目生命周期的后期实现。但是，它对我们选择格式和工具非常有帮助。
工作特性集
没有特别的顺序……
- 特定于语言的语法突出显示:开发人员文档将严重依赖于代码片段。仅仅使用单行字体是不够的。当代码按照所涉及的编程语言进行颜色编码时，有助于理解。
- 支持多种编程语言(CSS, HTML,ASP。网c#,VB。网一些主题可能需要在同一空间内结合HTML、CSS和Javascript以及服务器端代码。在某些情况下，可能需要使用相同的语言显示不同的方法(例如，普通Javascript和ES6)。
- 能够使用代码块和内联代码显然，我们需要同时适应长代码段和短代码段。
- 基于文件的:这允许以原子的方式单独分配和管理主题。翻译人员可以简单地为他们的语言创建一个新文件。它还使管理内容变得更加容易，类似于管理源代码版本的方式。
- “Githubbable”:作为一个开源项目，社区能够以类似于DNN项目的方式为Docs项目做出贡献是至关重要的。这将为用户提供通过Pull Requests进行贡献的能力，为本地开发克隆项目，甚至为他们自己使用而分叉项目。
- 可以定位的:能够被翻译成其他语言
- 可嵌入的图像/视频有些东西只能用视觉来表达。
- 贡献者信贷:由于这是一个社区项目，我们应该提供一种方式来认可个人的努力。
- URL控制:为每个主题构建地址的能力，以指示主题、口语、DNN版本，并尽可能地在内容层次结构中显示主题的上下文。理想情况下，URL结构应该是可理解的和足够一致的，这样您就可以，例如，编辑URL来切换版本。
- 内部链接到文档中的主题
- 快速链接:我们希望为用户提供一种简单的方法来复制链接到页面，这样它就可以快速分享在其他场所，如Facebook和Twitter以及DNN论坛。
- 盘旋的定义:也叫“滴”。由于我们不能假设用户会按顺序阅读一系列主题，悬停定义将使内容使用术语以达到清晰和简洁的目的，同时允许不熟悉术语的用户单击或悬停在该词上以查看定义或解释。
- 包括:我们希望尽可能避免重复代码/内容，因此定义可重用组件或内容块的能力将减少维护并鼓励一致性。
- 搜索引擎优化:虽然我们不一定对“在谷歌上排名第一”感兴趣，但这里的目的是让用户能够提出谷歌的问题，并在结果中看到答案。这类似于当你在谷歌上搜索“javascript array splice”时，你会得到MDN (Mozilla Developer Network)文档
拼接方法。数组原型。
- 搜索:这对于用户尽可能高效地找到他们需要的信息至关重要。理想情况下，我们需要提前输入功能和智能搜索。
一些结论
上面的特性列表并不详尽。然而，到目前为止，它已经影响了我们对项目所做的一些选择:
- DNN Docs项目将是一个GitHub存储库。除了公开内容外，大多数潜在贡献者已经拥有GitHub账户。可以通过Pull Requests进行修改。存储库可以被克隆到用户的环境中，也可以被分叉。GitHub的API还提供了一个灵活的平台，我们可以在上面构建额外的功能，比如对贡献者进行积分。
- 减价的格式:主题将是单独的标记文件。与GitHub一样，Markdown是一种潜在贡献者将熟悉的语法。它有限的语法对于不熟悉的用户来说很容易学习。它在不混合样式的情况下为内容提供结构。此外，它是纯文本，便于人类阅读和跨系统移植。还有许多库可以将格式转换为其他格式，如HTML甚至PDF格式。我们知道我们必须在与Markdown的交易中做出一些妥协。非常简单的使用方式可能会限制我们提供某些功能的能力。
- 静态站点生成:使用静态站点来记录内容管理系统的讽刺意味并没有在我们身上消失。虽然我们可以在DNN中编写一个自定义系统，但花在编程上的时间并不是花在创建文档上的时间。文档完成后，只有在发布DNN的新版本或需要进行修改时，网站才会更新。不需要在用户请求页面时动态生成页面。静态站点生成器生成HTML文件。因此，它们是高性能的，搜索引擎友好的，并且几乎可以在任何地方托管。虽然文档最终可能会托管在DNN站点内，但这不是我们目前的首要任务。
选择工具
考虑到上面的特性集，我们决定需要一个足够灵活的静态站点生成器，允许我们在未来必要时构建特性。许多生成器针对特定类型的内容，如博客。有些是专门为文档设计的。T这里甚至有一些用于创建和托管文档的服务。虽然这些工具和系统使我们能够快速开始，但它们通常不像我们所希望的那样灵活，并且/或与我们为项目制定的其他目标(如可移植性和社区参与)相冲突。
选择工具很快就会演变成技术人员之间的宗教战争。没有一种工具能提供所有的功能，也没有一种工具能满足所有的需求，每个人都有充分的理由来说明他们的最爱是最好的。因此，该团队努力在其方法中采取务实的态度——寻找能够提供足够灵活性的工具，以满足我们的大部分需求，同时也不需要投入大量的时间。在这里，我们对Markdown的选择已经带来了回报。这意味着如果需要，内容可以移植到其他工具或系统。
我们的评估已经确定了两个开源竞争者:Metalsmith和React Static。我们还没有对两台发电机做出最终决定。Metalsmith本质上是一个带有插件的Javascript构建过程。它非常灵活，但是需要更多的前期工作来为我们的项目创建一个系统。我们目前正在评估React Static。顾名思义，它提供了react应用程序几乎所有的灵活性，同时生成静态HTML。考虑到DNN社区中react开发人员的社区不断增长，以及DNN本身对react的使用，我们应该有很多人可以定制工具或创建插件。
前进
虽然我们是一个小团队，但每周我们都在取得进步。目前，我们正在两条平行的轨道上工作:
- 创建内容体系结构:确定文档中应该包含的内容区域/主题。这包括现有文档中的主题以及缺失的区域。我们正在努力将其构建成一个连贯的框架(想想目录)。
- 通过实际创造内容来检验我们的假设和结论。我们正在创建示例内容，这些内容最终将出现在文档中。精心设计的内容允许我们测试所选工具集的限制，在功能集列表中尽可能多地进行测试。它还将使我们能够更好地理解我们需要为社区贡献指南、技术审查等建立的过程。
我希望这能让你对我们的进展和过程有一个相当全面的了解。我们正在努力工作，以达到我们可以向贡献者开放流程的地步。如果你有兴趣作为作者或评论员为这个项目做贡献，请告诉我自己或Clint Patterson。当然，我期待着在下面的评论中看到你的贡献。