如何编写 NumPy How-to#

How-to 直奔主题 – 它们

  • 回答一个重点明确的问题,或

  • 将一个广泛的问题缩小成用户可以选择的重点明确的问题.

一位陌生人问路…#

"我需要给我的车加油."

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

  • "三公里/英里,在 Hayseed Road 右转,它就在你的左边."

为新手添加有用的细节("Hayseed Road",即使它是三公里/英里处唯一的岔路口).但不是不相关的细节:

  • 不要也给出从 7 号公路出发的路线.

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

如果存在相关的背景信息(教程,解释,参考,替代方法),请通过链接将其引起用户的注意("从 7 号公路出发的路线","为什么加油站这么少?").

委派#

  • "三公里/英里,在 Hayseed Road 右转,按照指示牌走."

如果信息已经记录在案,并且对于 how-to 来说足够简洁,只需链接到它,可能在介绍之后("三公里/英里,右转").

如果问题很宽泛,缩小范围并重定向它#

"我想看看风景."

"观光"how-to 应该链接到一组更窄的 how-to:

  • 查找历史建筑

  • 寻找风景优美的观景点

  • 找到市中心

这些反过来又可以链接到更窄的 how-to – 因此市中心页面可以链接到

  • 找到法院

  • 找到市政厅

通过以这种方式组织 how-to,您不仅展示了需要缩小问题范围的人的选择,还为从较窄的问题开始的用户提供了答案("我想看看历史建筑","去市政厅怎么走?").

如果有很多步骤,请分解它们#

如果一个 how-to 有很多步骤:

  • 考虑将一个步骤分解成一个单独的 how-to 并链接到它.

  • 包含小标题.它们帮助读者掌握即将发生的事情并返回他们离开的地方.

当有 Stack Overflow,Reddit,Gitter…时,为什么要编写 how-to?#

  • 我们有权威的答案.

  • How-to 使该站点对非专家来说不那么令人生畏.

  • How-to 将人们带入网站并帮助他们发现此处存在的其他信息.

  • 创建 how-to 帮助我们以新的眼光看待 NumPy 的可用性.

How-to 和教程不是一回事吗?#

人们可以互换使用术语"how-to"和"教程",但我们遵循 Daniele Procida 的 taxonomy of documentation 来区分它们.

文档需要满足用户所在的位置. How-to 提供完成任务的信息;用户想要复制的步骤,不一定想了解 NumPy. 教程是温暖而模糊的信息;用户想要感受 NumPy 的某些方面(同样,可能不关心更深入的知识).

我们将教程和 how-to 都与 Explanations 区分开来,Explanations 是旨在提供理解而不是立即帮助的深入研究,而 References 提供有关 NumPy 某些具体部分(如其 API)的完整,权威的数据,但没有义务描绘更广阔的图景.

有关教程的更多信息,请参见 numpy-tutorials:content/tutorial-style-guide

此页面是 how-to 的示例吗?#

是的–直到带有问号标题的部分;它们解释而不是给出方向.在 how-to 中,这些将是链接.

On this page