引入新的Symfony文档欧宝体育电话欧宝娱乐app下载地址

什么我们可以做得更好吗?

在最近的一次会见Symfony文档维护人员(欧宝娱乐app下载地址瑞安,Wouter,基督教和哈维尔),瑞安表示沮丧和一个疯狂的想法:

我认为文档的布局/组织在www.oldmanjams.com上太混乱了。欧宝娱乐app下载地址我想完全重组的事情。

这个问题?从历史上看,文档被分为三个主要部分:

1. “书”(几章解释了从基础到高级功能);
2. “食谱”(独立的教程关注高级主题);
3. “组件”(文章解释了如何使用Symfony框架组件外)。欧宝娱乐app下载地址

但对于新手来说,这是令人困惑。你在哪里学习路由?你应该选择书,食谱或组件?在现实中,每一个话题展开成这三个部分。

甚至是挑战对我们来说:新Symfony缓存应解释在一本书的一章,在一系列的食谱教程组件本身还是?欧宝娱乐app下载地址

所以,我们决定投资严重的时间,使一个很大的变化。当水星项目诞生了。我们研究最相关的项目的文档(P欧宝体育电话HP,框架,开源与否),添加我们自己的想法,并发现一个新的文档结构,我们认为是一个巨大的进步。

新的文档结构欧宝体育电话

欧宝娱乐app下载地址Symfony文欧宝体育电话档现在分为两个主要部分:

• 开始短书,解释所有关于发展与Symfony应用的基本框架在六章。欧宝娱乐app下载地址这是文档的入口点,这是资源应该推荐给那些想了解Symfony;欧宝体育电话欧宝娱乐app下载地址
• 指南,其他的一切。他们是简短而集中教程一系列广泛的话题(电子邮件、数据库、日志、形式、服务等)

就是这样:没有更多的书,食谱和组件。每一个主题——从路由到安全&序列化——有一个单页面的链接所有相关文档。欧宝体育电话

新文档结构是平的,简单,而不是深和嵌套。比较2.3文档结构与2.7文档结构。新结构似乎“不干净”,但更容易寻找文档(如对于任何给定的话题。“任何有关路由”)。

你可以体验新的结构调整欧宝体育电话文档索引页。

我们是如何做到的

但重组整个文档?欧宝体育电话这将是一个令人生畏的任务和要求巨大的的工作量。这就是为什么瑞恩提出另一个疯狂的想法:

让我们说服雇主Symfony的“投资”,让我们“水星项目”工作整整一周时间。欧宝娱乐app下载地址

他们同意!KnpUniversity瑞安赞助的工作,basecom赞助的基督徒的工作,SensioLabs哈维尔的作品,Wouter奉献自己的赞助个人时间。总共花了超过150小时更新。

大感谢这些公司支持Symfony项目这么大的投资资源。欧宝娱乐app下载地址

因为我们是做所以许多变化,(几乎每一个文件是感动),我们在一个私人存储库。这允许我们工作快速、避免任何混乱的公共文档库过程中(如。“一半的书不见了!为什么?”)。

除了新结构,我们有时间关注其他一些事情:

• 许多文章缩短、简化和组织重写:我们积极长解释搬进自己的专用页面和链接。例如,当你第一次学习形式,包括近200行是适得其反验证组的详细信息。现在有自己的文章。
• 我们还继续这一趋势在代码示例包括更多的评论,而不是长段落的解释。
• 我们添加了一些改进文档的样式,如更新终端代码块和其他几个变化更明显。我们也关闭了几个问题报道公众symfony-docs库。欧宝娱乐app下载地址

当然,当你移动成百上千的文件和处理成千上万的话说,可能会有一些错误。如果事情看起来奇怪的或很难找到,打开一个问题让我们知道。

和一个特别感谢法帮助合并必要的修改Symfony.com基础设施。欧宝娱乐app下载地址