如何编写一个 NumPy 操作指南#

操作指南直接切入要点——它们

  • 回答一个专注的问题,或者

  • 将一个广泛的问题缩小为用户可以选择的聚焦问题.

一个陌生人询问了方向…#

“我需要给我的车加油.”

给出一个简短但明确的回答#

  • “三公里/英里,在海西德路右转,它在你的左边.”

为新手添加有用的细节（”Hayseed Road”,尽管它是三公里/英里处的唯一转弯处）.但不添加无关的细节:

  • 也不要从7号路线给出指示.

  • 不要解释为什么这个镇上只有一个加油站.

如果有相关的背景（教程、解释、参考、替代方法）,请通过链接引起用户的注意（”从7号路线出发”,”为什么加油站这么少?”）.

Delegate#

  • “三公里/英里,在Hayseed路右转,跟随标志.”

如果信息已经记录并且足够简洁以用于操作指南,只需链接到它,可能在其前加上介绍（”三公里/英里,向右转”）.

如果问题广泛,请缩小并重定向它#

“我想看看风景.”

查看景点 操作指南应链接到一组更具体的操作指南:

  • 寻找历史建筑

  • 寻找风景瞭望点

  • 找到城镇中心

而这些可能会反过来链接到更详细的指南——因此,城镇中心页面可能会链接到

  • 找到法院

  • 找到市政厅

通过这种方式组织操作指南,您不仅为需要缩小问题范围的人展示了选项,还为那些从更具体问题开始的用户提供了答案（”我想看历史建筑”,”去市政厅怎么走?”）.

如果有许多步骤,请将它们分开#

如果一个操作指南有很多步骤:

  • 考虑将一个步骤分解成单独的操作指南并链接到它.

  • 包含小标题.它们帮助读者理解即将到来的内容并返回到他们离开的地方.

当有 Stack Overflow、Reddit、Gitter 等资源时,为什么还要写操作指南?#

  • 我们有权威的答案.

  • 操作指南使网站对非专家来说不那么令人生畏.

  • 操作指南将人们带入网站,并帮助他们发现这里的其他信息.

  • 创建操作指南帮助我们以新的视角看待 NumPy 的可用性.

操作指南和教程不是一回事吗?#

人们经常互换使用”操作指南”和”教程”这两个术语,但我们根据 Daniele Procida 的 文档分类法 进行了区分.

文档需要满足用户的需求.*操作指南* 提供即学即用的信息;用户想要复制步骤,不一定想要理解NumPy.*教程* 提供温馨的信息;用户想要感受NumPy的某些方面（同样,可能不在乎更深层次的知识）.

我们将教程和操作指南与 解释 区分开来,解释是深入探讨,旨在提供理解而不是即时帮助,以及 参考 ,它们提供了关于NumPy某些具体部分的完整、权威数据（如其API）,但不一定需要描绘更广阔的图景.

更多教程,请参见 Learn to write a NumPy tutorial

这个页面是操作指南的示例吗?#

是的 – 直到带有问号标题的部分;它们解释而不是给出指令.在一个操作指南中,这些会是链接.

On this page