Как написать руководство по NumPy

Руководства по использованию 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 следует указать ссылки на набор более узких руководств:

Найти исторические здания
Найти живописные смотровые площадки
Найти центр города

и эти руководства, в свою очередь, могут ссылаться на ещё более узкие руководства — так страница о центре города может ссылаться на

Найти суд
Найти мэрию

Организуя руководства таким образом, вы не только показываете варианты для людей, которым нужно уточнить свой вопрос, но и предоставили ответы для пользователей, которые изначально задают более узкие вопросы («Хочу посмотреть исторические здания», «Куда идти к мэрии?»).

Если шагов много, разбейте их на части

Если руководство содержит много шагов:

Подумайте о выделении шага в отдельное руководство и ссылке на него.
Включите подзаголовки. Они помогают читателям понять, что следует дальше, и вернуться к тому, что было пропущено.

Зачем писать руководства, когда есть Stack Overflow, Reddit, Gitter…?

У нас есть авторитетные ответы.
Руководства делают сайт менее устрашающим для новичков.
Руководства привлекают людей на сайт и помогают им открыть для себя другую полезную информацию.
Создание руководств помогает нам взглянуть на удобство использования NumPy новыми глазами.

Разве руководства и учебные пособия не одно и то же?

Люди используют термины «руководство» и «учебное пособие» взаимозаменяемо, но мы проводим различие, следуя классификации документации Даниэле Проциды.

Документация должна соответствовать потребностям пользователей. How-tos предлагают информацию для быстрого решения; пользователь хочет шаги для копирования и не обязательно хочет понять NumPy. Tutorials — это информация «для души»; пользователь хочет понять некоторый аспект NumPy (и опять же, может или не может заботиться о более глубоких знаниях).

Мы отличаем как учебные пособия, так и руководства от Explanations, которые представляют собой углублённый анализ, нацеленный на понимание, а не на немедленную помощь, и от References, которые предоставляют полные, авторитетные данные о конкретной части NumPy (например, о его API), но не обязаны предоставлять более широкую картину.

Дополнительную информацию о учебных пособиях см. в руководстве по учебным пособиям.

Является ли эта страница примером руководства?

Да — до разделов с заголовками с вопросительным знаком; они объясняют, а не дают инструкции. В руководстве они были бы ссылками.