如何写一个NumPy操作指南

如何直截了当——他们

  • 回答一个有重点的问题,或者

  • 将广泛的问题缩小为用户可以选择的重点问题。

一个陌生人问路。。。

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

给出一个简短而明确的答案

  • "Three kilometers/miles, take a right at Hayseed Road, it's on your left."

为新来者添加有用的细节(“干草路”,尽管它是三公里/英里的唯一岔道)。但不是无关的:

  • 也不要在7号公路上指路。

  • 别解释为什么镇上只有一个加油站。

如果有相关背景(教程、说明、参考、替代方法),请通过链接(“7号公路的方向”、“为什么加油站这么少?”)引起用户的注意。

代表

  • "Three km/mi, take a right at Hayseed Road, follow the signs."

如果这些信息已经被记录在案,并且足够简洁,可以在介绍之后链接到它(“3公里/英里,右转”)。

如果问题是广泛的,狭窄的和重定向它

“我想看看风景。”

这个 See the sights how-to应该链接到一组更窄的how-to:

  • 寻找历史建筑

  • 寻找风景了望台

  • 找到市中心

而这些又可能链接到更窄的how-tos——因此市中心页面可能链接到

  • 找到法院

  • 找到市政厅

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

如果有很多步骤,就把它们分开

如果操作指南有许多步骤:

  • 考虑将一个步骤分解成一个单独的操作方法并与之链接。

  • 包括副标题。它们可以帮助读者理解即将发生的事情,并返回到他们离开的地方。

当堆栈溢出,Reddit,Gitter…,为什么要写how-to呢。。。?

  • 我们有权威的答案。

  • 如何使网站不那么禁止非专家。

  • 如何让人们进入网站,并帮助他们发现其他信息,在这里。

  • 创建how-to有助于我们从新的角度看待NumPy的可用性。

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

人们可以互换地使用术语“how-to”和“tutorial”,但我们遵循Daniele Procida的方法来区分 taxonomy of documentation .

文档需要满足用户的需求。 How-tos 提供“完成”信息;用户希望复制步骤,而不一定想理解NumPy。 Tutorials 是温暖的模糊信息;用户想要对NumPy的某些方面有一种感觉(同样,可能关心也可能不关心更深入的知识)。

我们将教程和how-to与 Explanations 是一种深度潜水,目的是给予理解而不是立即的帮助,以及 References ,它提供了NumPy的一些具体部分的完整、自动的数据(比如它的API),但没有义务描绘更广阔的图景。

有关教程的更多信息,请参见 tutorial how-to .

这个页面是一个如何操作的例子吗?

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